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[57] ABSTRACT 

A computer operating system manages events. An ap- 
plication program or another part of the operating sys- 
tem defines an event monitor to monitor one or more 
types of events on its behalf. When each of the moni- 
tored events occurs, the event monitor is signalled and 
stores the event signal. Under certain conditions, the 
event monitor can notify an event handler, and the 
event handler can access the stored event signals. The 
event monitor can be defined and established dynami- 
cally, i.e. throughout operation of the computer with- 
out stopping or relinking the computer system. In the 
absence of an event monitor which is interested in an 
event, signals of the event are nevertheless stored. 
When an interested event monitor is subsequently estab- 
lished, the previously stored event signals are trans- 
ferred to the interested event monitor. Thus, the event 
handler has the benefit of previous event signals. The 
event can be a trace event, and the event handler associ- 
ated with each event monitor can receive and handle 
the trace events in real time. 

20 Claims, 20 Drawing Sheets 
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DYNAMICALLY ESTABLISHED EVENT 
MONITORS IN EVENT MANA GEMENT 
SERVICES OF A COMPUTER SYSTEM 

BACKGROUND OF THE INVENTION 

The invention relates generally to computer operat- 
ing systems, and deals more particularly with event 
management services within a computer operating sys- 
tem. 10 

During the course of operating a computer system, 
many types of events can occur, for example, pressing 
of an enter (function) key on a keyboard, loading of data 
from a disk into memory, or occurrence of severe errors 
or trace events, etc. Data may be associated with the 15 
event such as a character key that was pressed before 
the enter key or the name of the disk that was loaded. 
Previously known operating systems manage events 
such that when the event occurs, the operating systems 
notify one or more application programs executing 20 
within the system that are interested in the event and 
furnish associated event data, if any. After notification, 
the application program or programs can process the 
event data, or take other action in response to the event 
notification. 25 

A prior art IBM System/38 operating system man- 
ages events in the following manner. Each of the events 
is defined with a name from a predetermined set of 
numerical names, consisting of a class, type and sub- 
type. The operating system reserves certain of the pre- 30 
determined names to represent common hardware and 
software events, and makes the other names available to 
application programs to identify other events. Applica- 
tion programs also can dynamically define event moni- 
tors to receive notification of defined events. When the 35 
event occurs, the operating system or the application 
that detects the event calls an EventSignal function, and 
then continues with other processing. The EventSignal 
function signals one or more of the event monitors 
which are interested in the event, i.e. all of the event 40 
monitors which name events having the same class, 
type, and subtype identification as found in the event 
definition. Generic type and/or subtype specifications 
are also allowed. If there is more than one interested 
event monitor, the EventSignal function signals the 45 
interested event monitors in a broadcast mode, i.e. sub- 
stantially simultaneously. Then, the event monitor(s) 
notify respective event handling subroutines of applica- 
tion program(s) which are interested in the event, to act 
upon the event notification and/or process the event 50 
data. 

The event handlers operate synchronously or asyn- 
chronously relative to the occurrence of the events. In 
an asynchronous "trap" mode, the event handler re- 
quests notification of an event but does not wait idly for 55 
the event to occur if it has not yet occurred. When the 
event occurs and the respective event monitor is sig- 
nalled, the event monitor notifies the event handler by 
sending an interrupt followed by the event data. In a 
synchronous "test** mode, the event handler periodi- 60 
cally asks the event monitor whether the event has 
occurred, and if so, responds to the event and/or pro- 
cesses event data. If the event has not occurred, then the 
event handler performs other work. In a synchronous 
"trap" mode, the event handler requests the event noti- 65 
fication and event data once, waits in a sleep mode until 
the event occurs; and is awakened with the event notifi- 
cation. The System/38 operating system also supports 
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dynamic enabling and disabling of event monitors. A 
disabled event monitor will not notify the correspond- 
ing event handler of an event. Also, in the System/38 
operating system, it is possible to mask an event handler 
against receipt of event signals. 

Certain types of events such as program trace events 
are generated periodically. The System/38 operating 
system allows specification of a maximum number of 
events and associated event data to be retained, tied to 
an interested event monitor, or specification that the 
events and associated event data should be retained 
without limit while an interested event monitor is dis- 
abled. In the former case, when the maximum number 
of events and associated event data is exceeded, subse- 
quent new events and associated event data which ex- 
ceed the maximum level are discarded. 

While the System/38 operating system provides a 
substantial amount of control and efficiency in manag- 
ing events and permits associated application programs 
to participate in defining the event management ser- 
vices, further improvements are desirable to permit an 
operating system to more efficiently and more compre- 
hensively manage the events according to the specific 
requirements of the computer system and the associated 
application programs. 

Accordingly, a general object of the present inven- 
tion is to provide event management services which 
efficiently and comprehensively manage events and 
permit associated application programs and other parts 
of the computer system to tailor the event management 
services to their specific needs. 

Another object of the present invention is to provide 
event management services of the foregoing type which 
permit associated event signallers, event deflners and- 
/or event handlers to operate in an efficient and opti- 
mum manner. 

SUMMARY OF THE INVENTION 

The invention resides in a computer operating system 
which manages events. An application program or an- 
other part of the operating system defines an event 
monitor to monitor one or more types of events on its 
behalf. When each of the monitored events occurs, the 
event monitor is signalled and stores the event signal. 
Under certain conditions, the event monitor can notify 
an event handler, and the event handler can access the 
stored event signals. The event monitors can be defined 
and established dynamically, i.e. throughout operation 
of the computer without stopping or relinking the com- 
puter system. In the absence of an event monitor which 
is interested in an event, signals of the event are never- 
theless stored. When an interested event monitor is 
subsequently established, the previously stored event 
signals are transferred to the interested event monitor. 
Thus, the event handler has the benefit of previous 
event signals. 

The event can be a trace event, and the event handler 
associated with each event monitor can receive and 
handle the trace events in real time. 

BRIEF DESCRIPTION OF THE FIGURES 

FIG. 1 is block diagram illustrating key components 
of an operating system providing event management 
services according to the present invention, and associ- 
ated application program threads and hardware. 

FIGS. 2 (a-c) form a flowchart illustrating operation 
of the operating system of FIG. 1 when an event occurs 
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and an interested application program thread, while in a operating system responses to the event. The operating 

wait mode, is notified of the event system only recognizes the defined events. 

FIG. 3 is a flowchart illustrating an EventDiscard The operating system or application program signals 

function of the operating system of FIG. 1. an event to communicate the occurrence of the event. 

FIG. 4 is a flowchart illustrating an Event- S The event signal is always associated with the process 

MonitorReset function of the operating system of FIG. which signals the event An event can be defined so that 

1. its signal is recognized only within this process or else 

FIG. 5 is a flowchart illustrating operation of the throughout the entire session containing this process, 

operating system of FIG. 1 when an event occurs and The event signal can include data associated with the 

an interested application program thread, while in a test 10 event and a key which specifies particular occurrences 

mode, is notified of the event of the event or a subset of types of event data such as the 

FIGS. 6 (a-b) form a flowchart illustrating operation source of the data, 

of the operating system of FIG. 1 when an event occurs If an application program . or other function within 

and an interested application program thread, while in a the operating system 11 is interested in receiving notifi- 

trap mode, is notified of the event. 15 cation of an event and the event data, if any, the applica- 

FIG. 7 is a flowchart illustrating a broadcast mode of tion program or other operating system function defines 

signalling two event monitors which are interested in an event monitor. The definition specifies one or a com- 

the same event bination of events, of the same or different type, of 

FIG. 8 is flowchart illustrating a propagation mode of interest to the event monitor. In the embodiment of the 

signalling two event monitors which are interested in 20 present invention described herein in detail, if more 

the same event than one occurrence of the same type of event is re- 

FIG. 9 is a block diagram illustrating chaining of two quired to satisfy the event monitor, then the event type 

event monitors within the operating system of FIG. 1, is listed more than once in the event monitor definition, 

which event monitors are both interested in the same (Alternately, each event type can be listed just once in 

event 25 the event monitor definition, and a count provided for 

FIG. 10 is a block diagram illustrating chaining of each event type to indicate the minimum number of 

five event monitors within the operating system of FIG. events of that type required to satisfy the event moni- 

1, which event monitors are interested in different sets tor.) The definition can also specify a key with each 

of events. event name to limit the event occurrences of interest to 

FIG. 11 is a flowchart illustrating an EventDelete 30 the event monitor. The event monitor can monitor 

function of the operating system of FIG. 1. event signals provided by other program threads within 

FIG. 12 is a flowchart illustrating an EventEnable the same process or signals of events which have been 

function of the operating system of FIG. 1. defined with session scope. The event monitor defini- 

FIG. 13 is a flowchart illustrating an EventMonito- tion also specifies the number or "count" of distinct 

rEnable function of the operating system of FIG. 1. 35 event signals, i.e. the number of the specified events 

FIG. 14 is a flowchart illustrating an EventSelect which must have occurred at least once, which are 

function of the operating system of FIG. 1. required to "satisfy" the event monitor. Only when the 

FIG. 15 is a flowchart illustrating an EventMonitor- event monitor is satisfied will the event monitor give 

Select function of the operating system of FIG. 1. the associated event handler access to stored event 

FIG. 16 is a flowchart illustrating an EventMonitor- 40 signals. To provide such access, the event handler 

Delete function of the operating system of FIG. 1. makes a request to the event monitor, and if the event 

FIG. 17 is a flowchart illustrating an EventMonitor- monitor is satisfied, the event monitor will notify the 

Create function of the operating system of FIG. 1. event handler that the event monitor is satisfied and the 

FIG. 18 and FIG. 19 are flowcharts illustrating the location of the stored event signals. This request can 

trace management services of the operating system of 45 take the form of an EventTrap, EventWait or Event- 

FIG. 1. Test call. After receiving notification that the event 

DETAILED DESCRIPTION OF THE 

PREFERRED EMBODIMENTS prOC f^ ^ event data. The manner of mterpretmg the 

event data is based on a private protocol between the 
Referring now to the drawings in detail wherein like 50 event signaller and event handler, and is established 
reference numerals indicate like elements throughout separately for each named event The event manage- 
the several views, FIG. 1 illustrates an event manage- ment services within operating system 11 provides a 
ment services portion of a multitasking operating sys- channel for delivering the event notification and event 
tern generally designated 11 according to the present data to the event handler. After the event handler re- 
invention. The operating system 11 is preferably pro- 55 trieves and processes the event data, the event monitor 
grammed in executable form onto a computer readable must be reset before the event handler can retrieve and 
medium such as a magnetic disk or tape, loaded into the process new event signals. 

computer memory 21 and executed on a CPU 19. How- The event management services within operating 
ever, the operating system 11 or part thereof could also system 11 comprise event definers 12a, b, resultant event 
be implemented by equivalent hardware. 60 definitions 16a-d, event monitors 2Sa~d, event signal- 
Operating system 11 and associated application pro- lers 18a, 6, and an event signal manager 26. Although 
grams provide many functions which are described in not shown, the operating system 11 could also include 
more detail below. The functions can be grouped into event monitor definers and event handlers. FIG. 1 also 
the following categories: event defining, event signal- illustrates event definers 13a, b, event signallers 15a, 6, 
ling, event monitor creating, event monitoring, event 65 event monitor definers Yla-d, and event handlers 
monitor processing and event handling. lAa-d, within respective application program threads 
An event definition includes an event name to iden- that run on operating system 11. While each of the 
tify the event and attributes of the event to control some foregoing application program threads \Za~d, \4a-d, 
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15a; 6 and Yla-d may be a member of a different com- accessing data, sending data, dispatching a new thread, 
puter process, typically each pair of event monitor de- suspending a thread, etc). An accounting event is use of 
finers and event handlers (17a, 14a), (17ft 146), (17c; the computer system which may result in a charge to 
14c) and (17<£ ltd) is part of the same process, and the user. The application programs can define any type 
either each pair of event definers and event signallers is 5 of event such as the completion of a function, a check- 
part of the same process or resides within operating point in the function, data creation, data deletion, appli- 
system 11, or the event definer is within the operating cation program error events (ex. a user entry error) or a 
system and the event signaller is outside the operating request for responsive action. For example, if the appli- 
system as an application program. ^on program wants to control a robotic arm, the 

The following is a high level description of the opera- 10 application program can define an event which is a 

tion of operating system 11 and associated application request to move the arm, and subsequently signal the 

program threads. The event signallers 18a,£ and 15a, 6 eventf ie ^ requestj and provide event data to define 

detect the occurrence of events, and signal the event how much ^ m what direc tion to move the arm. The 

signal manager 26 with an indication of the occurrence operating system or the application programs can define 

of the event, the event name, event key (i.e subset of 15 ^ events at ^ - e durin imtiali2ationi 

types of event data accompanying the event and spe- at fot mvocation 0 f a service that detects the event, or 

cific event data. In response, the event signal manager at Qther ^ ^ event . defmed b ^ ^ 

compares the ^e of the signalled event to those in the EventCreate function 40 event sigmd nM ^ a 

even^fimtions Ife^ to detennme if the named event u md definitioil parameters The call for 

has been defined and, if so, to read attributes of the 20 fil „J£~ La ~mTT^ a VT c . + 

event The attributes indicate whether the event signal- J* ^°\f d f ch Action withm event sig- 

ler must be required to wait for the event to be handled j£ ? » deSCnb t d m ^nV^ 

before procig with other work or whether the Mana ^^on Gills" below 

event signaller must be permitted to proceed with other ^ Ba f^ V*™*™ * <^> event defini- 

work during event handling, a maximum number of 25 *°? 1^ eludes an event name and important attn- 

event signals that can be stored if there are currently no but f or charactenst ! cs of ^ event Each event name is 

event monitors which are interested in the event, and a * character string having a length and composition 

broadcast or propagation mode for notifying multiple detennined by the event definer, and provides the pn- 

event monitors which are interested in the event. Based mary "**«ificatioii of the event The attributes include 

on the first attribute, the event signal manager either 30 of ^ event loose ^S™ 1 ^ mode of 

causes the event signaller to wait for event handling to signalling the interested event monitors) 2Sa-d, and 

be completed or permits it to continue processing be- operational status of the respective event signaller lSa,b 

fore event handling is completed. The event signal man- or 1Sa > b durin S the event notification and processing, 

ager also reviews the definitions of event monitors Tbz event definition also includes enable and select 

2Sa-d to determine if one or more event monitors have 35 fields ^ described below with reference to FIG. 12 and 

been defined which reference, Le. are interested in, the 14 Aho > 321 described in more detail below with refer- 

named event with limiting event key. If not, the event ence to mG ' event signaller calls an EventSig- 

signal manager stores the event signal, tied to the event factum 49 within the event signal manager which 

definition, in accordance with the second attribute of reads the attributes of the named event to determine in 

the event definition. However, if at least one event 40 now t0 manage the event, 

monitor is interested in the named event with limiting The scope of the event name attribute indicates either 

event key, the event signal manager signals the event a sin S le process or an entire session in which the event 

monitor with the event notification and event data. If name has significance. If an event name has process 

there are two or more interested event monitors, then only, then only the process which defined the 

the event signal manager signals the interested event 45 event may signal the event and only those event moni- 

monitors in the broadcast or propagation mode as speci- tors defined in that process which reference the event 

fied in the event definition. The event monitor defini- name can be signalled by the EventSignal function, 

tion indicates the maximum number of signals of each However, if an event name has session wide scope, then 

listed event that can be stored bound to the event moni- all event monitors that reference the event name can be 

tor for subsequent transmission to the interested event 50 signalled by the EventSignal function after receiving 

handler, and the number of distinct event signals re- the event signal regardless of what process signalled the 

quired to "satisfy" the event monitor. If satisfied, each event. Each event name having session wide scope must 

signalled event monitor is eligible to notify the respec- be unique within the system; however, each event name 

tive event handler of the event upon request by the having process scope need only be unique within the 

event handler in the requested manner, i.e. wait, trap or 55 process that signals and monitors the event, 

test mode. The event handlers respond to the event The loose signal limit attribute is the number of 

notification and/or process the event data, if any. events and associated event data ("loose signals" 41) 

The following is a more detailed description of the that are stored at the direction of the EventSignal func- 

present invention. The operating system can define tion in association with the corresponding event defini- 

events such as process creation, process deletion, begin 60 tion after the event is defined and the event occurs, but 

command, end command, command not found, reset, in the absence of any event monitors that are currently 

program load, program unload, console output com- interested in the event After the loose signal limit of 

plete, console input available, error, timer, trace, I/O event signals is reached, each subsequent event signal is 

and accounting events. An error event is, for example, a stored at the expense of the oldest event signal which is 

program check, a severed connection or other system 65 then erased. The storage of loose signals is important 

failure. A timer event is the end of a timing period. A because an event monitor may be defined later which is 

trace event is the completion of a program subroutine, interested in the event and benefit from the previous 

thread or significant step of a program (for example, event signals. 
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The mode of signalling attribute refers to the manner handler processes the event data. If the event represents 
of signalling more than one event monitor that is inter- a "call" to an exit routine, then the process which sig- 
ested in the same event. In a broadcast mode, the Event- nailed or called the exit routine should be suspended 
Signal function signals all interested event monitors until the event is handled, and the event attribute should 
without contingency, usually at substantially the same 5 indicate the synchronous treatment. An exit routine is a 
time. The event definition should indicate the broadcast block of code which is usually provided by a user of 
mode when all of the interested event monitors can operating system 11 to perform a user-specific or instal- 
benefit from the event notification and event data re- lation-specific function. Such functions can be optional, 
gardless of the nature of the event For example, if the additional or otherwise external to the operation of the 
event is the loading of data from a disk into memory and 10 product. If no event monitor for the exit routine event 
there are multiple event handlers which are interested has been defined, then the calling program continues to 
in reading the data, then it is most efficient to broadcast execute and there is no system failure. Also, the exit 
the event notification and event data to the event han- routine can reside in a different process from the caller 
dlers (via the associated event monitors) soon after the to shield the resources of the calling process from the 
occurrence of the event and without any contingency 15 exit routine. The event handler can provide an exit 
so that those event handlers may be dispatched by the routine, in which case control typically should not re- 
operating system for optional concurrency. In a FIFO turn to the caller until the exit routine is executed; there- 
propagation mode, the event monitors are subject to fore, the exit routine should be defined as an event with 
notification in order of creation of the event monitors, the synchronous attribute. 

and in a LEFO propagation mode, the event monitors 20 The event monitor definers lla-d (or other event 

are subject to notification in reverse order of creation of monitor definers not shown, within operating system 

the event monitors. The event handler associated with 11) define the event monitors 2Sa~d respectively by 

each event monitor that is signalled controls whether calling an EventMonitorCreate function 42 and specify- 

the next event monitor in the sequence is signalled as to ing the event monitor parameters. Each call identifies 
the occurrence of the event To do this, each event 25 one or more event names, respective event keys, the 

handler that receives the event signal calls an Event- number of occurrences of distinct events to satisfy the 

MonitorReset function to permit propagation of sped- event monitor, and a bound signal limit for each event 

fied event signals in the current signal set to the next and other attributes of the event monitor. The key may 

event monitor in the sequence. Each event handler in be a **wildcard" indicating that the event monitor is 
the sequence can also call an EventDiscard function to 30 interested in all types of the named event, or may be a 

prevent propagation of one or more event signals to the subset of the types of named events. The event monitor 

next (and all downstream) event monitors in the se- definition also includes enable, select, delete, wait and 

quence. Event signal propagation rules are applied on a trap fields described below. As described above, after 

process basis; when interested event handlers reside in receiving the name of the event and event key from the 
different processes, the event signal is always delivered 35 event signaller and verifying that the named event has 

to at least one event monitor in each of the processes. been defined, the EventSignal function reads the event 

This control is described in more detail below with monitor definitions to determine which one or ones, if 

reference to FIGS. 7 and 8, and permits each event any, recite the event name and key. If one or more such 

handler in the sequence to avoid processing of the event event monitors have been defined, then the EventSignal 
data by subsequent event handlers in the sequence when 40 function calls them in the broadcast or propagation 

the event handler determines that the system will not mode as specified in the event definition, 

benefit by propagation of the event signal. For example, The use of the keys simplifies the definitions of the 

assume that the event is a severe failure, a function of events which can list a general event name such as the 

the first event handler in the sequence is to analyze the pressing of an enter key or the loading of a disk into 

nature of the failure, and a function of the next event 45 memory, while the event monitor definition limits the 

handler in the sequence is to recover from the failure. If event signalling to the event monitor based on the key 

the failure is so severe that recovery is not possible, then within the event monitor definition. For example, the 

the first event handler should block the propagation of event monitor key may be limited to a specific set of 

the event signal to the next event handler in the se- character keys or type of loaded disk, 

quence. Thus, the effect of the blocking is to improve 50 The next attribute listed above in the event monitor 

the overall efficiency of the system. definition, the number or count of distinct event signals 

The operational status attribute within the event defi- required to satisfy the event monitor, causes the event 

nition refers to the synchronous or asynchronous treat- monitor to withhold notification of the event signals to 

ment of the process which signals the event while the the associated event handler until after the specified 

EventSignal function signals the event monitor, the 55 number of distinct events named in the event monitor 

event monitor notifies the event handler, and the event definition have occurred. For example, an event han- 

handler acts upon the event and processes the event dler which has the function of recovering communica- 

data. For example, if the event is an error in the process tion errors may be interested in receiving notification of 

that signalled the event, then it may be preferable to the errors only when a total often communication facil- 

suspend the process that signalled the event (synchro- 60 ity errors and/or parity errors have occurred in order to 

nous treatment) until the error is recovered by the inter- justify further analysis; 1 a lesser number of the errors 

ested event handler. However, if the event represents may not be deemed significant enough to initiate recov- 

normal operation of the event signaller and the event ery. In this embodiment of the present invention, if the 

signaller should be ready to process other similar events communication error is listed ten times and the parity 

(asynchronous treatment), such as the pressing of a 65 error is listed ten times and the count is specified as ten, 

keyboard function key, then the event signaller process the breakdown between the number of errors of each 

should not be suspended while the event monitor is specified type is not critical to the satisfaction of the 

signalled and notifies the event handler and the event event monitor as long as a total of ten occurrences of 
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either or both types have occurred. However, if the 
communication error is listed five times and the parity 
error is listed five times and the count is ten, then five of 
each type of event must occur to satisfy the event moni- 
tor. Thus, the event monitor definer can specify a par- 5 
ticular number of occurrences of each event type of 
interest required to satisfy the event monitor. 

The last attribute listed above in the event monitor 
definition, the bound signal limit, is the number of un- 
processed event signals that can be stored at the direc- 10 
tion of the interested event monitor, bound to or associ- 
ated with each designated event in the interested event 
monitor. When the limit is exceeded, the oldest bound 
event signal is erased, and the newest event signal is 
bound to the event monitor. For example, a bound 15 
signal limit for the storage of a fixed number of trace 
events and data is useful to assist in trouble shooting an 
event condition, whereas additional, older trace data 
may not be useful because it may not reflect current 
problems. The bound signals are stored in a bound sig- 20 
nal set 47. When an event monitor is satisfied and an 
event handler requests event notification, the event 
monitor designates the oldest bound distinct event sig- 
nals as a current signal set 45 for access by the event 
handler. If more than one occurrence of the same type 25 
of event is required to satisfy the event monitor, then 
the current signal set includes at least the number of 
event signals for the type as required to satisfy the event 
monitor. 

Another attribute in the event monitor definition 30 
specifies whether or not the event monitor, when cre- 
ated, should receive signals of the type or types in 
which the event monitor is interested but which oc- 
curred before creation of the event monitor and are 
stored in the loose signal set. If so, the loose signals are 35 
transferred to the bound signal set 47 upon creation of 
the event monitor. Still another attribute in the event 
monitor definition specifies whether or not other pro- 
gram threads within the same process as the event han- 
dler should be suspended after the event monitor is 40 
satisfied and while the event handler receives the event 
notification and handles the event It may be important 
to suspend execution of the other program threads if the 
event is a system failure which requires an abend or an 
event which requires the event handler to take a "snap- 45 
shot" of the entire process. 

As noted above, typically each event monitor definer 
and associated event handler are part of the same pro- 
cess so that when a process wants to monitor an event 
or combination of events and handle the event or com- 50 
bination, the process defines the event monitor and 
provides an associated event handler that is notified 
pursuant to a call by the event handler to the Event- 
Test, EventTrap or EventWait function. The process 
can define or delete the event monitor and involve the 55 
event handler dynamically, i.e. at any time without 
relinking or interrupting other programs, by calling the 
EventMonitorCreate or EventMonitorDelete function 
and the EventTest, EventTrap or EventWait function. 
Also, multiple processes can define multiple event mon- 60 
itors and provide multiple event handlers for the same 
or different events or combinations of events. 

After receiving the call, the EventMonitorCreate 
function reads and stores all the parameters in the call 
(step 80 of FIG. 17). Next, the EventMonitorCreate 65 
function determines if an event monitor flag parameter 
indicates that loose signals should be bound (decision 
block 82). If so, the EventMonitorCreate function reads 
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the loose signal set associated with the definition of each 
event of interest to the event monitor to determine if 
there are loose signals with limiting key ("qualified 
events") of interest to the event monitor. To be of inter- 
est to the event monitor, the loose signals must either 
have session scope or have process scope with the event 
being defined by the same process that defined the event 
monitor. If there were no prior occurrences of the event 
or if another event monitor was previously defined to 
have interest in the event, then there will be no loose 
signals. If there are loose signals of interest, the Event- 
MonitorCreate function transfers all these loose signals 
to the event monitor (step 86), and the event monitor 
binds them to itself in accordance with its bound limits 
as described below with reference to step 115 of FIG. 2. 
Then, the EventMonitorCreate function returns to its 
caller (step 88). 

At any time after an event monitor definer \la-d 
defines an event monitor, the associated event handler 
can request notification when the event monitor is satis- 
fied. The types of requests include test, trap and wait 
modes, and the event handler selects the desired mode 
with a call to an EventTest function 50, EventTrap 
function 52, or EventWait function 54. The effect of 
each call depends of the state of the respective event 
monitor. 

If the event monitor is not yet satisfied, then the fol- 
lowing occurs: 

1) The EventTest function, if called by the event 
handler, reports to the event handler the state of 
each event name-event key pair (referenced in the 
event monitor associated with the event handler), 
i.e. whether the named event with appropriate key 
has occurred or been deleted. 

2) The EventWait function, if called by the event 
handler, suspends the event handler until the event 
monitor is satisfied. When satisfied, the event moni- 
tor awakens the event handler and reports the state 
of each of the event name-event key pairs. 

3) The EventTrap function, if called by the event 
handler, informs the operating system that a trap 
routine should be run when the event monitor is 
satisfied. Because the operating system does not 
know in what environment the trap routine will 
run, no information regarding the condition of the 
event monitor is initially passed to the trap routine. 
Therefore, when the event monitor is satisfied, the 
event monitor invokes the trap routine and the trap 
routine calls the EventTest function to obtain a 
report on the state of each event name-event key 
pair. If at the time the event monitor is satisfied, 
both an EventTrap and EventWait function have 
been called, the EventWait function takes prece- 
dence and the trap routine is not run. 

If the event monitor is satisfied, but is not yet acti- 
vated (Le. not yet asked by an event handler for event 
notification), then the following occurs: 

1) The EventTest function, if called by the event 
handler, activates the event monitor and causes the 
event monitor to establish the current signal set and 
report to the event handler the state of each event 
name-event key pair. 

2) The EventWait function, if called by the event 
handler, activates the event monitor and causes the 
event monitor to establish the current signal set, 
awaken the event handler and report the state of 
each event name-event key pair. 
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3) The EventTrap function, if called by the event 
handler, causes the event monitor to establish the 
current signal set and run the specified trap routine. 
An event monitor is "active" (after the event monitor 
is satisfied and an event handler has requested event 
notification) while the event handling program is exe- 
cuting as a result of a call to the EventWait function, 
EventTrap function or EventTest function. If the event 
monitor is currently active, then the following occurs: 

1) The EventTest function, if called by the event 
handler, reports to the event handler the state of 
each event name-event key pair. 

2) The EventWait function, if called by the event 
handler, resets the event monitor and suspends the 
event handler until the event monitor is again satis- 
fled. 

3) The EventTrap function, if called by the event 
handler, lists with the event monitor the address of 
the trap routine, overwriting the address of any 
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event definition attribute, whether or not the event 
signaller should be stopped (synchronous treatment) 
until the event is handled (decision block 107), and if so, 
causes the event signaller to stop (step 108). In either 
case, the EventSignal function next reads the event 
monitor definitions 2&a-d to determine if any event 
monitors are interested in Event A and whatever limit- 
ing key, if any, limits the interest of the event monitor 
(step 109 and decision block 110). If no event monitor is 
interested in the event and limiting key, the EventSignal 
function binds the signal to the event definition in ac- 
cordance with the loose signal limit (step 111). If the 
loose signal limit has already been attained, then the 
oldest loose signal is discarded. If there are one or more 
event monitors which are interested in the event name 
with limiting key and are selected-on (decision block 
112), the EventSignal function provides the event signal 
(event name and event data) to all of them nearly simul- 
taneously if the event definition specifies the broadcast 



trap routine previously associated with this event 20 mode attribute (step 114a), or to the first event monitor 



monitor. 

When an event monitor is active, new event signals 
which it monitors are still bound to the event monitor 
and are processed by the event monitor after the Event- 
MonitorReset function 62 is executed. Then, the event 25 
monitor examines the remaining bound signals, and if 
they are sufficient to satisfy the event monitor, the event 
monitor is again eligible for activation. 

FIG. 2 is a flowchart illustrating operation of operat- 
ing system 11, particularly the EventSignal function 49, 30 
event monitor 28a and event handler 14a, when the 
event handler calls the EventWait function 54. During 
step 90, the event definer 12a within the operating sys- 
tem defines an Event A (with session scope) although 
event definer 13a within an application program could 35 
just as well have defined Event A. For example, Event 
A is the pressing of an enter key on a keyboard follow- 
ing the pressing of a character key. Concurrently or at 
a later time, event monitor definer 17c within an appli- 
cation program defines an event monitor 28a which is 40 
interested in Event A by calling the EventMonitorCre- 
ate function (step 92). Later, event handler 14a calls the 
EventWait function 54 to indicate that the event han- 
dler will synchronously wait for event monitor 28a to 
be signalled of an event, and informs the EventWait 45 
function where the event data should be stored (step 
94). In response to the call, the EventWait function sets 
a wait bit in event monitor 28a, lists the caller (event 
handler 14a) with the event monitor 28a (step 95), and 



in the sequence if the event definition specifies the prop- 
agation mode attribute (step 1146). In the illustrated 
example, there is only one event monitor which is inter- 
ested in the named event with limiting key and is select- 
ed-on. However, if all event monitors that were inter- 
ested in the event with limiting key were selected-off, 
then the event monitors would not be notified and the 
event signals would be bound to the event definition in 
loose signal set 41 (step 111). The signalled event moni- 
tor 28a binds the event signal to itself by storing the 
event signal in bound signal set 47. Next, the event 
monitor determines if it is satisfied by comparing the 
number of distinct event signals stored in the bound 
signal set 47 to an "event—count" field in the event 
monitor definition (step 116). The number of distinct 
signals of events of interest to the event monitor indi- 
cated by the event count must occur in order to satisfy 
the event monitor. As previously noted, one type of 
event can be listed more than once in the event monitor 
definition. In the alternate embodiment of the invention 
described above, in step 116, the event monitor deter- 
mines if the specified number of occurrences of each 
event type have occurred to satisfy the event monitor. 
If the event monitor is not yet satisfied, no further ac- 
tion is taken by the event monitor or the associated 
event handler as a result of this occurrence of Event A. 
However, if the event monitor is satisfied, then the 
event monitor proceeds to determine if there is an 
EventWait call outstanding by reading the wait bit 



renders the event handler in a sleep mode whereby it 50 (decision block 117). In this example, the wait bit was 



waits for the event notification without performing any 
other operations (step 94). At a later time, a person 
presses the character key and then the enter key, and a 
subroutine (event signaller 18a) which continually mon- 
itors the keyboard detects the pressing of the keys. In 55 
response, event signaller 18a calls the EventSignal 
function 49 and provides the event name, limiting key, 
if any, and event data (step 100). The EventSignal func- 
tion 49 reads the event definitions 16a-d to determine if 

Event A has been defined in the same process as the 60 signal set (step 1121) and then processes the event data 
signaller or with session scope (step 102 and decision (step 1122). Next, the event handler decides whether 
block 104). If not, the EventSignal function returns an any, all or none of the event signals in the current signal 
error code to the event signaller (step 105). However, in set should be available for propagation, even though the 
the illustrated example, Event A has been defined with event handler 14a need not know if there are any other 
session scope, and the EventSignal function notes in 65 event monitors which are interested in any of the events 
decision block 106 that the event definition is selected- or even if the event definition specified the propagation 
on (as described below with reference to FIG. 14). mode. If event handler 14a does not want to make any 
Then, the EventSignal function decides, based on the or all of the event signals available for propagation in 



set in step 95, and the event monitor then proceeds to 
establish a current signal set 45 by designating from the 
bound signal set 47 all distinct signals (step 118), and 
awakens the event handler listed by the EventWait 
function (step 119). Upon awakening, the event handler 
determines that the caller is the event monitor (and not 
an EventMonitorDelete function described below) (de- 
cision block 1120), calls an EventRetrieve function 56 
to retrieve the alpha-numeric data stored in the current 
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any case, the event handler 14a calls the EventDiscard set function calls an EventM onitorDelete function 68 
function 58 specifying event monitor 28a and any or all (step 185) described below. If not, or after receiving the 
of the event signals in the current signal set to be dis- return from the EventMonitorDelete function, the 
carded. This will block any possible propagation of the EventMonitorReset function returns to its caller (step 
specified event signals from event monitor 28a's current 5 182). 

signal set (step 1125). FIG. 5 is a flowchart illustrating operation of the 

When called, the EventDiscard function erases the operating system 11 when event handler 14c calls the 
specified signals from the current signal set of the EventTest function. In step 150, either the event definer 
named event monitor 28a (step 186 of FIG. 3). Next, the 126 or 136 defines Event B. Concurrently or at a later 
EventDiscard function determines if the event signal- 10 time, event monitor definer 176 defines an event moni- 
ler(s) of the discarded event signal(s) are in the wait tor 286 which is interested in Event B (step 151). Next, 
state pursuant to this attribute of the signalled event event handler 146 calls the EventTest function 50 re- 
definition^), and if so, awakens them (decision 188 and questing status information about event monitor 286 
step 190). Then, the EventDiscard function returns to (step 153). In response, the EventTest function locates 
the event handler (step 191). After step 191, or if deci- 15 event monitor 286 (decision block 154), reads the bound 
sion block 1124 indicates that the event handler made all signal set of event monitor 286 (step 155) and then de- 
the event signals available for propagation, the event termines if the event monitor is satisfied (decision block 
handler can directly call the EventMonitorReset func- 156). If so, the EventTest function activates the event 
tion illustrated in FIG. 4, or return to the event monitor monitor and establishes the current signal set (step 157). 
which then calls the EventMonitorReset function. The 20 After the event monitor returns to the Event Test func- 
event handler can also terminate itself in which case a tion at step 158 or if the event monitor was not satisfied, 
function which assists in the termination will call the the EventTest function advises the event handler 146 
EventMonitorReset function. Normally, the event nan- whether the event monitor is satisfied, which event 
dler makes the return to the event monitor after steps signals will be in the current signal set upon satisfaction 
1120-1125. The event handler only calls the Event- 25 of the event monitor, and the length of each signal (step 
MonitorReset function directly to indicate terniination 158). If event monitor 286 is satisfied (decision block 
of processing prematurely, for example, to allow a trap 160), then the event handler will call the EventRetrieve 
routine to be re-entered, or to allow an event monitor to function to obtain the event data (step 164), process the 
be polled successively with the EventTest function. data (step 166) and then execute steps 1124-1126 de- 
Also, because an event monitor is associated with an 30 scribed above. However, if the event monitor was not 
event handler, when the event handler is terminated, satisfied, then the event handler avoids steps 164, 166 
the event handler calls the EventMonitorReset function and 1124-1126, and can perform other work, 
indirectly. FIG. 6A, B form a flowchart illustrating operation of 

In step 172 of FIG. 4, the EventMonitorReset func- the operating system 11 when the EventTrap function 
tion reads the current signal set to identify any remain- 35 52 is called. In step 130, either event definer 126 within 
ing signals. The current signal set will be full if decision the operating system 11 or event definer 136 within any 
block 1124 led directly to step 1126, but will be partially application program defines Event C. Concurrently, or 
or completely empty if the event handler called the at a later time, event monitor definer 17c defines an 
EventDiscard function in step 1125. If the current sig- event monitor 28c which is interested in Event C (step 
nal set is not empty (decision block 173), the Event- 40 131). Next, event handler 146 calls the EventTrap func- 
MonitorReset function reads the event definition for tion 52 specifying that event monitor 28c should notify 
each event signal in the current signal set to determine a trap routine within the event handler 14c when the 
the mode of signalling of other interested event moni- event monitor is satisfied, and the name or address of 
tors (step 176). For each event signal, if the mode of the trap routine (step 132). After step 132, the event 
signalling is the broadcast mode (decision block 177), 45 handler 146 can perform other work; it does not idly 
then the EventMonitorReset function proceeds to step wait for event notification in the event trap mode. In 
180 to erase the event signal from the current signal set response to the call, the EventTrap function sets an 
of the event monitor named in the EventMonitorReset event trap bit and lists the trap routine's name or address 
call (because the other interested event monitors al- with the event monitor 28c (step 133). Subsequently, 
ready received the event signal). However, if the event 50 Event C occurs, and event signaller 186 or 156 calls the 
definition indicates the FIFO or LIFO propagation EventSignal function 49 (step 134). Then, the EventSig- 
mode for any of the event signals, then decision block nal function executes steps 102-114 as described above, 
177 leads to step 174 in which the EventMonitorReset and the event monitor executes step 115-117 as de- 
function reads the other event monitor definitions to scribed above; however, step 117 indicates that the 
determine if any are interested in that event signal (step 55 event wait bit has not been set Therefore, the event 
174). If so (decision block 175), then the Event- monitor proceeds to determine that the event trap bit 
MonitorReset function signals the next event monitor in has been set (decision block 120), and then calls the trap 
the sequence for the respective event signal, and then routine within event handler 14c (step 122). The trap 
proceeds to step 180. Thus, the event signals remaining routine calls the EventTest function 50 illustrated in 
in the current signal set for the events which are defined 60 FIG. 5 specifying the event monitor, event name and 
for the propagation mode are propagated to the next event key (step 138). Then, the EventTest function 
event monitor in the sequence for each event. That executes steps 154-158 as described above. Based on the 
event monitor also executes the sequence of steps information received from the EventTest function, the 
115-119 illustrated in FIG. 2, and the respective event trap routine determines that the event monitor has been 
handler executes steps 1120-1126. After step 180, the 65 located (decision block 139). Then, the trap routine calls 
EventMonitorReset function determines if the event the EventRetrieve function to retrieve the event data 
monitor 28a has been marked for deletion as described from the current signal set (step 140), processes the 
below (decision block 181). If so, the EventMonitorRe- event data (step 142), and executes steps 1124-1126 as 
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described above. If the trap routine returns without (step 428) and the EventWait function sets the wait bit 
having reset the monitor, the event monitor calls the and lists the caller (step 429). Subsequently, Event I 
EventMonitorReset function when it receives the re- occurs, and the event signaller calls the EventSignal 
turn from the event handler (step 128). function 49 (step 430). In response, the EventSignal 
FIG. 7 is a flowchart illustrating broadcast of an 5 function executes steps 102-114, and in step 102 notes 
event signal to two interested event monitors. In step from the event definition that the FIFO propagation 
380, an Event H is defined and the definition includes mode has been specified. In step 110, the EventSignal 
the name of the event and an indication that all inter- function also learns that event monitors 28c and 2Sd are 
ested event monitors should be notified in the broadcast both interested in Event I, and from the order of chain- 
mode, i.e. substantially simultaneously. Concurrently or 10 mg 0 f the event monitors that event monitor 28c was 
at a later time, the event monitor definer 17a defines an created first Then, in step 114& the EventSignal func- 
event monitor 28c which is interested in Event H (step tion signals the first interested event monitor in the 
382), and event monitor definer 176 defines an event sequence, event monitor 28a Then, event monitor 28c 
monitor 286 which is also interested in Event H (step executes steps 115-119, and in step 119 awakens event 
384) The event handler Ua then calls the EventWait 15 ^er 14c Then, the event handler 14c executes steps 

£r^£% m £L a ^ P c m ^L aW l^ g 1120-H24 and 1126, and in decision block 1124 decides 
notification of EventH(ste^ ^ the event ^ ^ ^ fof 

tion sete the wait bit for event momtor 28a and hsts the don . ^ ^ 14c retunis £ e ^ 

£ 1 l£ 0n T T { ^^P\ S r^ lyt *S on monitor * ^ep 1126 which automatically caUs the 
IIS tM "?* the EventWait function and 20 EventMonitorReset function (step 128). However, the 

wait bit for event monitor 286 and lists the caller for 1124 ^ ^ " * e * en ^ m curren j 
event monitor 28b (step 389). Subsequently, Event H "* not 5f. av ^ le fo . r Propagation and 
occurs, and the event signaller calk the EventSignal 25 ^ ^ Even^iscard fimcdon 58 specifymg 
function 49 (step 390). In response, the EventSi^al ^ be discarded If m step 1125, event 
function executes steps 102-114 as described above, and ***** 14c * * e event S1 S°^ m 
in step 102 determines that the broadcast mode has been 2™°* Slgnal 301 should ^ discarded (which in the 
specified. In step 110, the EventSignal function learns ^^ted example is the lone signal for Event I), then 
that two event monitors 28a and 286 are both interested 30 m step 186 of ^ 3 ' ^ discarded and the Event- 
in the Event H. In step 114a, the EventSignal function MonitorReset function would not propagate anything 
signals both of the event monitors nearly at the same t0 event monitor because the current signal set 
time; neither event monitor can prevent signalling to would (decision block 173 of FIG. 4). In the 
the other event monitor. After receiving the event sig- illustrated example, however, event handler 14c does 
nal, event monitor 28a executes steps 115-119, and the 35 not discard the signal for Event I, event monitor 28c is 
associated event handler 14a executes steps 1120-1126 reset » ^ the EventMonitorReset function signals the 
as described above. Similarly, after receiving the event event monitor 2Hd in step 178 of FIG. 4 which executes 
signal, event monitor 2Sb executes steps 115-119, and ste P s M5-119. Then, event handler 14d executes steps 
the associated event handler 146 executes steps 1120-4126. If event handler 14d discards Event I in step 
1120-1126 as described above. The respective event 40 1125, then when the EventMonitorReset function is 
monitors 28a and 286 execute step 128. Therefore, after called, decision block 173 of FIG. 4 would avoid an 
Event H occurs, both event handlers 14a and 146 re- attempt at propagating the event signal because the 
ceive the event notification and event data nearly simul- current signal set would be empty. If event handler 14d 
taneously, and neither event handler can prevent the does not discard Event I in step 1125, then when the 
other event handler from receiving the event notifica- 45 EventMonitorReset function is called, decision block 
tion and event data. 175 would avoid an attempt at propagation because 

FIG. 8 is a flowchart illustrating propagation of an there are no more interested event monitors, 

event signal from a first event monitor to a second event FIG. 10 illustrates a more complicated example of 

monitor in a sequence, with the right of the first event chaining of event monitors to indicate order of propaga- 

monitor in the sequence to prevent propagation of the 50 tion. Event monitor 2Se is interested in Events M, N and 

event signal to the second event monitor in the se- O, and was created first. Event monitor 28/ was created 

quence. In step 420, Event I is defined, and the defini- after event monitor 284 is interested in events M and P 

tion includes the FIFO propagation attribute which and is chained from the Event M reference in event 

means that interested event monitors should be sig- monitor 2Se to indicate that both event monitors are 

nailed sequentially in order of creation. Concurrently or 55 interested in Event M. Event monitor 2Sg was also 

at a later time, event monitor definer 17c defines event created after event monitor 28c, is interested in the 

monitor 28c which is interested in Event I (step 422), events N and O, and is chained from the event N and 

and event monitor definer 27o* defines event monitor event O references in event monitor 28c to indicate that 

280* which is also interested in Event I (step 424). As both event monitors are interested in Events N and O. 

illustrated in FIG. 9, when each event monitor is ere- 60 Similarly, event monitors 28A and 28/ were created after 

ated, it is chained or referenced by address to the previ- event momtor 28/ are interested in events M and P, 

ously created event monitor which is interested in the respectively, and are chained from the respective event 

same event. This indicates the order of creation. After M and event P references in the event monitor 28/ 

the event monitors are defined, event handler 14c calls Thus, when it is necessary to propagate each event 

the EventWait function specifying event monitor 28c 65 signal from any of these event monitors, the Event- 

(step 426), the EventWait function sets the wait bit and MonitorReset function reads the event monitor defini- 

lists the caller (step 429), event handler 14a* calls the tion to identify the next event monitor in the FIFO or 

EventWait function specifying the event monitor 28a* LEFO sequence that is interested in the particular event 
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At any time after defining an event, the process EventMonitorEnable function 64 can be called to dis- 

which defined the event can delete or modify the event able an event monitor after creation, or enable a dis- 

definition by calling an EventDelete function 69 or an abled event monitor. Event signals will be bound to a 

EventModify function 71. The EventDelete function is disabled event monitor, but a disabled event monitor 

illustrated in FIG. 11. The EventDelete function does 5 cannot be satisfied. 

not affect current processing of the current signal set, FIG. 13 is a flowchart illustrating the EventMonito- 

but reads the bound signal set for each event monitor rEnable function. After Event E is created (step 220), 

which is interested in the event to be deleted and the and an interested event monitor is created (step 222), the 

loose signal set 41 for the event to determine if there are event handler can call the EventMonitorEnable func- 
any event signals which are not in the current signal set 10 tion specifying that the named event monitor should be 

(decision block 296). If so, they are discarded (step 298). disabled (step 224). In response, the EventMonitorEna- 

Next, the EventDelete function indicates in the defini- ble function marks the EventMonitor definition with a 

tion of each event monitor which is interested in the disabled indicator (step 226). When Event E occurs, the 

event that the event has been deleted (step 300). Then, event signaller calls the EventSignal function (step 228), 

the EventDelete function determines if there are any 15 and the EventSignal function executes steps 102-114 as 

event monitors which are interested in the event and described above. Then, the event monitor binds the 

have outstanding EventWaits (decision block 302). If event signal to the event monitor (step 115), but on 

so, the EventDelete function calls the event monitor at account of the disabled indicator in the event monitor 

step 119 (step 303) and steps 120-128 are executed. In definition, the event monitor does not count this or any 

step 120, the event handler will learn that the event has 20 signal toward satisfaction of the event monitor in deci- 

been deleted and consequently that the event monitor sion block 116, and no further action is taken by the 

associated with the event handler may never be satis- event monitor. 

fied. Next, the EventDelete function determines if there When an event is originally defined, monitoring is 

are any event monitors which are interested in the event automatically started. If the monitoring remains started, 

and have outstanding event traps (decision block 304). 25 the EventSignal function signals the interested event 

If so, the EventDelete function calls the event moni- monitors) in the manner described above in FIGS. 2, 5 

tor(s) at step 122 (step 305), and then steps 138-142 and and 6a, b. However, an EventSelect function 60 can be 

1124-1126 are executed. In step 158 of the EventTest called to stop monitoring specific events, or to start 

function (which was called by the trap routine in step monitoring after monitoring has been stopped. When 

138), the EventTest function notifies the trap routine 30 monitoring is stopped, subsequent event signals are not 

that the event monitor may never be satisfied. Finally, bound to any event monitor in the process which issued 

the EventDelete function deletes the event definition the EventSelect function. 

(step 306). FIG. 14 illustrates the EventSelect function. In step 
The EventModify function is called to change the 250, the Event F is defined and monitoring is automati- 
loose signal limit or operational status of signalling attri- 35 cally started. Then, the event monitor is defined (step 
butes within the event definition. Changes to the loose 252). Subsequently, the event handler calls the Event- 
signal limit attribute take effect immediately whereas Select function and specifies that monitoring of a named 
changes to the operational status attribute do not take event should be stopped (step 254). In response, the 
effect until a subsequent signal is issued. EventSelect function marks the event definition for the 
When an event is originally created, it is automati- 40 named event as monitoring stopped (step 256). Subse- 
cally enabled. The EventEnable function 44 can be quently, Event F occurs, and the event signaller calls 
called to disable an event after the event is created or to the EventSignal function (step 258). The EventSignal 
enable a disabled event When an event is disabled, function executes steps 102 and 104 as described above, 
signals for the event are bound to the interested event and then determines from the event definition that mon- 
monitor(s) but do not count toward satisfaction of the 45 itoring should be stopped (decision block 106). Conse- 
event monitors). quently, the EventSignal function binds the event signal 
FIG. 12 is a flowchart illustrating the EventEnable to the event definition in accordance with the loose 
function. In step 202, the event definer 13a defines signal limit within the event definition (step 262). Be- 
Event D, and in step 204 the event monitor definer 21 d cause monitoring has been stopped, the EventSelect 
defines event monitor 28d which is interested in Event 50 function does not signal any event monitor, not even the 
D. Next, the event handler 14d which is associated with interested event monitor. 

event monitor 28d can call the EventEnable function When any event monitor is initially created, monitor- 
and specify that Event D should be disabled (step 206). ing is automatically started for the event monitor. How- 
In response, the EventEnable function marks the event ever, the EventMonitorSelect function 66 can be called 
definition for Event D as disabled (step 208). Subse- 55 to stop monitoring by an event monitor, or to start 
quently, Event D occurs, the event signaller calls the monitoring by a stopped event monitor. The Event- 
EventSignal function (step 210), and the EventSignal MonitorSelect function 66 differs from the Event- 
function executes steps 102-114 as described above. MonitorEnable function 64 because the signal of inter- 
Then, the event monitor binds the event signal to event est to a stopped event monitor is not bound to the event 
monitor 28rf but indicates that the event signal should 60 monitor, whereas the signal of interest to a disabled 
not count toward satisfying the event monitor (decision event monitor is bound to the event monitor, 
block 212 and step 213). Then, the event monitor pro- FIG. 15 is a flowchart illustrating the EventMonitor- 
ceeds to step 116 and subsequent steps 117-119 as de- Select function. In step 270, Event G is defined, and in 
scnbed above in FIG. 2, but in step 116 does not count step 272 an interested event monitor 28b is defined. In 
the latest occurrence of Event D toward satisfaction of 65 step 274, the event handler 14* calls the EventMonitor- 
thc A event mo * utor - . Select function specifying that event monitor 28b 
As noted above, when an event monitor is originally should stop monitoring. In response, the EventMonitor- 
created, it is automatically enabled. However, the Select function marks the event monitor definition as 
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monitoring stopped (step 276). After Event G occurs eluding the events of interest to the event monitor, can 
and the event signaller calls the EventSignal function be dynamically modified. If an event type is deleted 
(step 278), the EventSignal function executes steps from a list of events of interest to the event monitor, 
102-114 as described above and in decision block 112, then bound signals of the deleted event type are pro- 
determines that monitoring for event monitor 2Sb has 5 cessed as described in the EventMonitorDelete function 
been stopped. As a result, the EventSignal function 68. If an event type is added to the event monitor defini- 
binds the event signal to the event definition for Event tion, then any loose signals of that event type are pro- 
G but does not signal event monitor 28b or bind the cessed as described in the EventMonitorCreate function 
signal to event monitor 28b. It should be noted, that if 42. in fact, the event monitor modification is function- 
there are other event monitors which are interested in 10 ally equivalent to atomically deleting the event monitor 
Event G and have their monitoring started, then these with the EventMonitorDelete function 68 and recreat- 
other event monitors would receive the event signal in mg th e event mon itor with the EventMonitorCreate 
step 112, and the event signal would not be bound to the function 42 with the following exceptions. Bound sig- 
event definition. nals of evente that are of interest to the event monitor 
At any tone after creation of an event monitor, the 15 both ^foxe md ^ ^ modification ^ ne ither dis- 
process that created the event monitor can also ddete aaded nor propagated except if the bound signal limitis 
tte event monitor by callmg an EventMomtorDelete decrease d and there are more bound signakthan the 

f"*^ * t ? u,Mfi ? m ™' 16 - ^ a f~ f decreased limit, in which case the excesToldest bound 

tenmnated, die process ^ calls the EventMomtorDelete ^ ^ ^cause ^ event monitor 

tocdon to delete all of the event monitors that were 20 definition ^ modified atomically (Le . in one step), there 

defined by the process In step 400, the EventMomtor- h no ^ of losin si ^ for ^ 

Dele tefunctionreads themformaU^ while the event momtor definition is being modified. 

signals, status, etc.) associated with the event momtor. 0 

If the event monitor is active (decision block 402), the EVENT SIGNAL MANAGER FUNCTION 

EventMonitorDelete function marks the event monitor 25 CALLS 

with an indication that the event momtor should be 

deleted when it is next reset (step 404), which causes the — — — > 

EventMonitorReset function to call the EventMonitor- EventCreate retcode 
Delete function during step 185 of FIG. 4. However, 

the EventMonitorDelete function does not interfere 30 



isncode 
cvenCname 
event name_Jength 

with processing of the current signal set If the event event_flag 
monitor was found to be inactive in decision block 402, event fla g . si re 

or after the event monitor becomes inactive after pro- ^Utow u t^ eriod 
cessing of the current signal set and a subsequent execu- 
tion of the EventMonitorReset function, the Event- 35 

MonitorDelete function removes the event monitor Parameters 
from the chain so that it is no longer accessible to any 

other function (step 406). Next, the EventMonitor- "EventCreate" is the name of the function being 
Delete function determines if any of the events in which invoked. 

the event momtor is interested are defined with the 40 "Retcode" is a signed 4-byte binary variable to hold 
propagation attribute and if there are any other inter- tne return code from EventCreate. A "return code" 
ested, downstream event monitors (decision block 408). indicates success or failure or error or lack of error of a 
If both conditions are satisfied, then the EventMonitor- 0311 or parameter. 

Delete function propagates each bound event signal "Rsncode" is a signed 4-byte binary variable to hold 
that meets these conditions to the next event monitor in 45 reason code from EventCreate, A "reason code" 
the respective sequence (step 410). The EventMonitor- indicates the reason for a failure or error of a call or 
Delete function discards any bound signals that do not parameter. 

meet both criteria (step 412). Next, the EventMonitor- "Event name" is a character variable containing the 
Delete function reads the event wait bit in the event name of the event to be defined, 
monitor to determine if there is an EventWait outstand- 50 "Event^ n a m e— length" is a signed 4-byte binary vari- 
ing (decision block 414). If so, the EventMonitorDelete able containing the length of event, name, 
function awakens the respective event handler and indi- "Event flag" is an array of 4-byte binary variables 
cates that the event monitor is being deleted (step 416). each element of which contains information about how 
Next, the EventMonitorDelete function reads the trap the event is to be managed. Only one option from each 
bit to determine if there is an event trap outstanding 55 of the following sets may be specified. If no option from 
(decision block 418). If so, the EventMonitorDelete a particular set is specified, the default is taken. The 
function invokes the trap routine (step 420). When the scope of the event name is indicated by process and 
trap routine invokes the EventTest function (step 138 of session; "vm_evn_ process— scope" where only this 
FIG. 6, the EventTest function will not locate the event process can monitor this event and only this process can 
monitor in decision block 139 of FIG. 6 and report to 60 signal this event, and "vm_evn_session_scope" where 
the trap routine that the event monitor does not exist. all processes in the session can both monitor and signal 
Then, the trap routine will return to the operating sys- this event The manner in which an event signal is deliv- 
tem, and the operating system implicitly calls the ered to multiple event monitors in a process is indicated 
EventMonitorReset function. Finally, the Event- as broadcast, FIFO or LIFO mode; "vm— evn__broad- 
MonitorDelete function erases the event monitor defini- 65 cast— signals" where the signal is delivered simulta- 
tion (step 422). neously to all qualifying monitors, "vm_evn_fifo_sig- 

In an alternate embodiment of the present invention, nals" where the signal is delivered to one qualifying 
any of the attributes of an existing event monitor, in- momtor at a time, in the order the monitors were cre- 
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ated, and "vm_evn_ lifo— signals" where the signal is 

delivered to one qualifying monitor at a time, in the Parameters 

order opposite that of event defined with the FIFO "EventDelete" is the name of the function being 

option. invoked. 

The treatment of the signaler is indicated as "vm_ev- 5 "Retcode" is a signed 4-byte binary variable to hold 
n-async— signals", "vni—evn— sync— thread signals", the return code from EventDelete. 
or "vm_evn_sync— process— signals". The vm_ev- "Rsncode" is a signed 4-byte binary variable to hold 
n— async signals indicates that the signaling thread is the reason code from the EventDelete. 
allowed to continue executing (the default). The vm ., "Event—name" is a character variable containing the 
wn gyn^ thr^H cignalc indicates that the signaling 10 name of the event whose definition is to be deleted, 
thread is suspended until signal processing is complete. "Event— name—length" is a signed 4-byte binary van- 
Signal processing in a process is considered complete able containing the length of event— name, 
when all qualifying monitors have completed process- 
ing of the signal or, if there are no qualifying monitors, . 
the signal has been discarded as a result of being the 15 EventDiscard reteode, 
oldest loose signal when the loose signal limit was ex- monitor_token, 
ceeded. An event monitor is considered to have com- index 



pleted processing a signal when that signal has become 
part of the current signal set of the event monitor and 2Q 

that event monitor has subsequently been reset. For Parameters 

FIFO and LIFO events, a bound signal may be explic- "EventDiscard" is the name of the function being 

Hly discarded via EventDiscard or implicitly discarded invoked 

if it is the oldest bound signal when the bound signal "Retcode" is a signed 4-byte binary variable to hold 

hunt of the event name-event key pair to which it is 25 the return code from EventDiscard. 

bound is exceeded. In either case, the processing of the -Rsncode" * a signed 4-byte binary variable to hold 

discarded signal by that process is considered complete. the reason oode from EventDiscard. 

If this is a session level event, all processes must have "Monitor token" is a signed 4-byte binary variable 

completed processing before signal processing is con- conts ^ ing ±t token which identifi e S the event monitor 

"^T??^ ^v^vn^ync-process^ignak 30 from whose current signal set a signal is to be discarded. 

mdicate that aU threads currently existing in the signal- A ^ of 0 may be used to identify the active event 

ing process with the exception of those threads running monitor which was most recently activa ted on the cur- 

as the result of an event monitor activated by this signal, rent thread 

are suspended to await the outcome of event process- ..^^ ^ a si ^ binary variable u^^g, 
ing. Threads running as the result of event monitor 3!,^ ^ ^ / vent name-address, eve£ 
activation may create additional threads which are not , „ rmt aAAr ^, c „„"T 

initially suspended. Upon EventMonitorReset how- hf^V^ tyeat -^-^^ ^ d e ?™' 
ever, the adrttional threads are treated as any ofter «- J ^- Jen * h arrays specified m the creat.cn of the 
thread ' event momtor, the event name and event-key pair 

tcr , " _ . ,, . ... , . . . , corresponding to the signal to be discarded. A value of 

^vent_fkg_**e"is a signed 4-byte bmary variable 40 Q £ ^ j^^t ^ signals m & current 
contaming the number of elements in the event-flag sjgJset are to be discarded, current 
array. 

"Loose— signal— limit" is a signed 4-byte binary vari- 

able containing the number of event signals that may be EventEnable retcode 

retained if no eligible event monitor exists to which to 45 rsncode 
bind the signal at the time the event is signaled. When number_o£_events 
the limit is exceeded, the oldest loose signal is discarded !v^ l 

to make room for the newest arrival. A value of 0 indi- even* «-n*Mement--mask 

cates that no loose signals are to be retained. A value of ' — 
— 1 means that the loose signal list is allowed to grow 50 

without limit, subject to the availability of virtual stor- Parameters 

age. Any other negative value is considered an error. «t?,™,+i:-„ui~» :„ *u ~ * *v r ^ v ■ 

"SignaLtimeouLperiod" is a signed 4-byte binary ^fkrt 8 
variable representing the tnaximum length of time spec- -Retcode" is a signed 4-byte binary variable to hold 
ified in nucroseconds, that a signaling thread should , he return ^ for S ventEn able. 
remam sussed awaitmg the wmpledon of process- -j^^e" * a signed 44,yte binary variable to hold 
me of the signal. A value of 0 indicates that the signal- A * , r *U 

* *t. j t - , - . . - 77 : the reason code from EventEnable. 

mg thread should wait indefinitely for the completion of »*r™i™ n r , • , . u ^ . U1 

.*L «i • T r*i. *i r * Al _ ^ Al _ . Number of events is a signed 4-byte binary variable 

signal processing- If the option specifying that the sie- ♦ u e * j * i 

r^r *\, . * . v ^ / * ,\ ™ ™? 60 containmg the number of event name and event-key 

nailing thread is to continue processing is included m • Q f in terest 

the event-flag array, then this parameter is ignored. "Event-name-address" is an array of num- 

ber_ of— events 4 -byte pointer variables each element 

Event Delete retcode of which contains the address of the name of an event 

nncode 65 whose occurrence is to be monitored. 

^" Lr^l i "Event name length" is an array of number— oL_e- 

even ength vents signed 4-byte binary variables each element of 

which contains the length of the event— name pointed to 



03/18/2004, EAST version: 1.4.1 



23 



5,355,484 



by the corresponding element of the event_joame_ ad- 
dress array. 

"Event— enablement— mask" is an array of number of 
events signed 4-byte binary variables each element of 
which contains the enablement mask of the even- 5 
t n a m e pointed to by the corresponding element of the 
event nam e ad dress array. The event enablement 
mask is maintained on a process basis; the EventEnable 
command affects the issuing process only. The value of 
the enablement mask determines the action to be per- 10 
formed, Le. 

"vm_evii_disable" which disables the event name 
indicated by the corresponding element of the even- 
t name address array, or 

"vm_evn_ enable" which enables the event name 15 
indicated by the corresponding element of the event 
name address array. 



EventModify 



retcode 
rsncode 
event— name 

event name length 

event flag 

event—flag— size 
loose signal limit 
signal timeout— period 
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signal., limit is to remain unmodified. Any other nega- 
tive value is considered an error. 

"Signal- time out-period" is a signed 4-byte binary 
variable representing the maximum length of time, spec* 
ified in microseconds, that a signaling thread should 
remain suspended awaiting the completion of process- 
ing of the signal. A value of 0 indicates that the signal- 
ing thread should wait indefinitely for the completion of 
signal processing. A value of — 1 means that the existing 
signal timeout— period is to remain unmodified. If the 
option specifying suspension of the signaler is not in- 
cluded in the event—flag array, then this parameter is 
ignored. 



EventMonitorCreate 
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retcode 
rsncode 
monitor— token 
monitor— flag 
monitor— flag— size 
number— of— events 
event— name— address 
event— name—length 
event— key address 
event— key— length 
bound— signal— limit 
event— count 



Parameters 

"EventModify" is the name of the function being 30 
invoked. 

"Retcode" is a signed 4-byte binary variable to hold 
the return code from EventModify. 

"Rsncode" is a signed 4-byte binary variable to hold 
the reason code from EventModify. 35 

"Event name" is a character variable which con- 
tains the name of the event whose definition is to be 
modified. 

"Event name length" is a signed 4-byte binary vari- 
able containing the length of event— name. 40 

"Event—flag" is an array of 4-byte binary variables 
each element of which contains information about how 
the event is to be managed. Only one option from the 
following set may be specified. If no option from this set 
is specified, the existing value of the option remains 45 
unmodified. The treatment of the signaler is indicated 
by vm— evn a sync— signals in which the signaling 
thread is allowed to continue executing (the default), 
vm_evn_sync— thread— signals in which the signaling 
thread is suspended to await the outcome of event pro- 50 
cessing, or vm — evn_sync_process_ signals in widen 
all threads in the signaling process, with the exception 
of those threads running as the result of a monitor acti- 
vated by this signal, are suspended to await the outcome 
of event processing. 55 

"Event— flag_size" is a signed 4-byte binary variable 

containing the number of elements in the event 

flag,, array. 

"Loose— signal -limit" is a signed 4-byte binary vari- 
able containing the number of event signals which may 60 
be retained if no eligible event monitor exists to which 
to bind the signal at the time the event is signaled. When 
the limit is exceeded, the oldest loose signal is discarded 
to make room for the newest arrival. A value of 0 indi- 
cates that no loose signals are to be retained. A value of 65 
— 1 means that the loose signal limit will be allowed to 
grow without limit, subject to the availability of virtual 
storage. A value of —2 means that the existing loose- 



Parameters 

**EventMonitorCreate" is the name of the function 
being invoked. 

"Retcode" is a signed 4-byte binary variable to hold 
the return code from EventMonitorCreate. 

"Rsncode" is a signed 4-byte binary variable to hold 
the reason code from EventMonitorCreate. 

"Monitor— token" is a signed 4-byte binary variable 
in which is returned a token with which to identify the 
event monitor on subsequent invocations of other event 
management functions. 

"Monitor— flag" is an array of signed 4-byte binary 
variables each element of which contains information 
about how the event monitor is to be managed. Only 
one option from each of the following sets may be speci- 
fied. If no option from a particular set is given, the 
default is applied. 

The longevity of the monitor is indicated by "vm 
evn_ no— auto— delete" which means that the event 
monitor persists until explicit EventMonitorDelete (the 
default), or "vm_evn_ auto_delete" which means that 
the event monitor is automatically deleted at first deac- 
tivation or EventMonitorReset The effect of monitor 
activation on dispatchability is indicated by "vm— ev- 
il— async— monitor" which means that all threads in the 
process containing the monitor remain dispatchable (the 
default), or "\Tn_evn_sync^process monitor" which 
means that all threads currently existing in the process 
containing the monitor, except the one on which the 
monitor is being activated (Le. the event handler for this 
event monitor), are suspended until the monitor is deac- 
tivated. The binding of loose signals to this monitor is 
indicated by u vm_ evn_ bind loose— signals" (the de- 
fault) which means that when the monitor is created, or 
monitoring is restarted via EventSelect or Event- 
MonitorSelect, any loose signals for which this monitor 
is qualified are bound to this monitor, or "vm_ evn— ig- 
nore— loose— signals" which means that no loose signals 
are bound to this monitor. 
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"Monitor_Jlag— size" is a signed 4-byte binary vari- 
able containing the number of elements in the 
monitor— flag array. 

"Number—of— events" is a signed 4-byte binary vari- 
able containing the number of event— name and even- 
t—key pairs of interest. 

"Event name— address" is an array of num- 
ber— of— events 4-byte pointer variables each element of 
which contains the address of the name of an event 
whose occurrence is to be monitored. 

"Event -name length" is an array of number— of—e- 
vents signed 4-byte binary variables each element of 
which contains the length of the event— name pointed to 
by the corresponding element of the event— name— ad- 
dress array. 

**Event__key— address" is an array of number— of— e- 
vents 4-byte pointer variables each element of which 
contains the address of a key that further characterizes 
the particular instance of the event name pointed to by 
the corresponding entry of the event— name— address 
array that is to be monitored. The key may be chosen to 
match exactly the key that will be carried by the signals 
of interest; or a partial key, possibly including wildcard 
characters, may be used to match a broader range of 
occurrences. "Event—key —length" is an array of num- 25 
ber— o£_ events signed 4-byte binary variables each 
element of which contains the length of the event—key 
pointed to by the corresponding element of the even- 
t-key— address array. The key may be null (that is, its 
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"Retcode" is a signed 4-byte binary variable to hold 
the return code from EventMonitorDelete. 

"Rsncode" is a signed 4-byte binary variable to hold 
the reason code from EventMonitorDelete. 

"Monitor— token" is a signed 4-byte binary variable 
containing the token which identifies the event monitor 
to be deleted. A value of 0 may be used to identify the 
active event monitor which was most recently activated 
on the current thread. 



EventMonitorEnable 



retcode 
rsncode 

number— of— monitors 

monitor—tokens 

monitor enablement masks 



20 



Parameters 

"EventMonitorEnable" is the name of the function 
being invoked. 

"Retcode" is a signed 4-byte binary variable to hold 
the return code from EventMonitorEnable. 

"Rsncode" is a signed 4-byte binary variable to hold 
the reason code from EventMonitorEnable. 

"Number— of— monitors" is a signed 4-byte binary 
variable containing the number of monitor— tokens of 
interest. 

"Monitor—tokens" is an array of number— of— moni- 



i , nv., * , - . . ' , m tors 4-byte pointer variables each element of which 

lengthmayb<^rfnos^ 30 thetokenof Aemonitor wMc h is to be enabled 

event is required to define the occurrence of interest; a 



35 



40 



null key in a monitor matches any key on a signal 

"Bound— signal limit" is an array of number— of—e- 
vents signed 4-byte binary variables each element of 
which contains the number of signals of the correspond- 
ing event name and event key pair that may be retained 
bound to the event monitor but unprocessed during an 
interval when the monitor is already active or testable 
or while the monitored condition remains unsatisfied. 
When the limit is exceeded, the oldest bound signal of a 
particular event name and event— key pair is discarded 
to make room for the newest arrival. The minimum 
permissible value is 1, indicating that only the most 
recent instance of each signal is to be retained. A value 
of — 1 means that the bound signal list is to be allowed 45 
to grow without limit, subject to the availability of 
virtual storage. Any other negative value, or 0, is con- 
sidered an error. 

"Event— count" is a signed 4-byte binary variable that 
contains the number of the specified event name and 
event— key pairs for which signals must be bound to the 
monitor for the monitored condition to be considered 
satisfied. The value must fall between 1 and num- 
ber— of— events. Alternately, in another embodiment of 
the present invention, an event— count is specified for 
each event type to indicate the number of occurrences 
of each event type required to satisfy the event monitor. 



or disabled. A value of 0 may be used to identify the 
active event monitor which was most recently activated 
on the current thread. 

"Monitor— enablement— masks" is an array of num- 
ber— of— monitors signed 4-byte binary variables each 
element of which contains the enablement mask for the 
monitor identified by the corresponding element of the 
monitor tokens array. The value of the enablement 
mask determines the action to be performed; i.e. "vm_ 
evn— disable" causes the disabling of the monitor identi- 
fied by the corresponding element of the monitor— tok- 
ens array, and "vnx_evn_ enable" causes the enabling 
of the monitor identified by the corresponding element 
of the monitor tokens array. 

EventMonitorQuery — An application program can 
call this function to obtain information about the defini- 
tion and status of a previously created event monitor. 



50 
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EventMonitorQuery 
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EventMonitorDelete 



retcode 
rsncode 
monitor— token 



Parameters 

'•EventMonitorDelete" is the name of the function 
being invoked. 



65 



retcode 
rsncode 

monitor— token 
monitor— flag • 
monitor— flag size 
monitor— flag count 
number_of— events 
even t__name_buffer_addr ess 
event namr buffer—length 
event namr Jength 
event— key__bufler— address 
event— key— buffer—length 
event— key—length 
bound— signal— limit 

bound signaL^count 

monitor— selection mask 

monitor enablement— mask 

event— count 

present— event count 

trap— routine— address 
trap— routine— name 
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„ "Event_name_ buffer—address" is an array of num- 

ber of events 4-byte pointer variables each element of 

"EventMonitorQuery" is the name of the function which contains the address of a character variable in 

being invoked. which is to be returned the name of an event whose 

"Retcode" is a signed 4-byte binary variable to hold 5 occurrence is to be monitored, 

the return code from EventMonitorQuery. "Event name— buffer— length" is an array of num- 

"Rsncode" is a signed 4-byte binary variable to hold ber— oL_events signed 4-byte binary variables each 

the reason code from EventMonitorQuery. element of which contains the length of the even- 

"Monitor— token" is a signed 4-byte binary variable t name buffer pointed to by the corresponding ele- 

identifying the event monitor about which information 10 ment of the event name buffer— address array, 

is to be returned. A value of 0 may be used to identify "Event name length" is an array of number— of— e- 

the active event monitor which was most recently acti- vents signed 4-byte binary variables in each element of 

vated on the current thread. which is returned the actual length of the event name 

"Monitor—flag" is an array of signed 4-byte binary which has been stored in the buffer pointed to by the 

variables in each element of which is returned informa- 15 corresponding element of the even t name buffer— ad- 

tion about how the event monitor is to be managed. array. If the name is longer than the buffer, it is 

Exactly one option from each of the following sets is truncated; if shorter, the excess space at the end of the 

included. buffer » unchanged. 

The longevity of the monitor is indicated either by "Event_key_bufTer_address" is an array of num- 
"vm_evn_no_auto_delete" which means that the 20 ber_oL_events 4-byte pointer variables each element of 
event monitor persists until explicit EventMonitor- which 0°****™ th « address 0 f a buffer in which to re- 
Delete or termination of the defining process, or "vm_ key that further characterizes the particular 
evn_auto_delete" which means that the event monitor msttt ^ e of *** event-name pointed to by the corre- 
is automatically deleted at first deactivation or Event- „ sponduig entry of the evenLname_buffer-array 
MonitorReset call. 25 wmch * monitored. 

The effect of monitor activation on dispatchability is "Event-key^_buffer^ength" is an array of number 

indicated by «Vm_evn_async_monitor» which means of events signed 4-byte bmary variably each e ement of 

that all threads in the process containing the monitor J™* ^ f 1^ taffcr P°"* ed "> b * 

rom „• jjc^^^ku uul A-4-~„n\ ^«™* „ the corresponding element of the event—key— buf- 

remain dispatchable (the default), or vm^vn_sync_ 3Q fer^dresVarray 

process_monitor which means that all threads cur- . , ; „ . - , . 

• *i • . • * . . Event— key_ length is an array of number— of— e- 

rently existing in the process containing the monitor, „^ fc , 0 - , fu**-ux - ■ ui ■ t. i «. * 

\ v u*i. ■* • ? • j * » , vents signed 4-byte binary variables m each element of 

except the one on which the monitor is being activated which » retume ? d ^ length of the 

( ^f^^^. event momtor), are sus- which has been stored m the bu | er mted to b ^ 

pended until me monitor is deactivated. . . 35 corresponding element of the EventJcey-bufiFer-ad- 

The binding of loose signals to this monitor is mdi- dress ff ^ k b { ^ ^ buff ft ^ 

catedeitherby \m^^md^oos^ig&s» which truncated; if shorter, the exccS space at the end of the 

means that any qualifying loose signals that exist at the buffer ^ unchanged 

time the monitor is created or selected-on are bound to "Bound-signal limit" is an array of number_of_e- 

the event monitor ^ (the default) or "vm-evn-tg- 40 vents signed 4-byte biliary variables in each element of 

nore-locse-signals which means that no loose signals which & returned ^ number of 4^ of ^ corre _ 

arebound to the monitor. spending event name and event key pair which may be 

The current activation state of the monitor is indi- retaine d bound to the event monitor but unprocessed 

cated by vm-evn-monitor-actiy^ which means duri ng an interval when the monitor is already active or 

that the monitored condition is satisfied and a signal 45 testa ble or while the monitored condition remains un- 

processing program is executing; "vm_ev- satisfied. When the limit is exceeded the oldest bound 

n_monitor-waiting" which means that the monitor is signal 0 fa particular event-name and event-key pair is 

not active, the monitored condition is not satisfied and discarded to make room for the newest arrival. The 

there is an outstanding EventWait associated with the minimum permissible value is 1, indicating that only the 

monitor, "vm_evn_monitor_trapping" which means 50 most recent instance of each signal is to be retained. A 

that the monitor is neither active nor waiting, the moni- va l U e of - 1 means that the bound signal list is allowed 

tored condition is not satisfied, and there is a trap rou- to grow without limi t, subject to the availability of 

tine associated with the monitor; or "vm_ ev- virtual storage. 

n-monitor_testable" which means that the monitor is "Bound-signaL-count" is an array of number_of_e- 

not active, waiting or trapping, the monitored condition 55 vents signed 4-byte binary variables in each element of 

may or may not be satisfied, and there is neither an which is returned the number of signals of the corre- 

outstanding EventWait or trap routine associated with sponding event name and event key pair which are 

the monitor. currently bound to the event monitor but unprocessed. 

"Momtor_flag_size" is a signed 4-byte binary van- "Monitor— selection-mask" is a 4-byte variable in 

able containing the number of elements in the 60 which is returned the selection mask for this monitor, 

monitor— flag array. This variable indicates whether this monitor is selected 

"Monitor— flag—count" is a signed 4-byte binary off or is selected on. 

variable in which is returned the number of elements in "Monitor— enablement— mask" is a 4-byte binary 

the monitor— flag array which have been set by Event- variable in which is returned the enablement mask for 

MonitorQuery. 65 this monitor. This variable indicates whether this moni- 

"Number— of— events" is a signed 4-byte binary van- tor is disabled or is enabled, 

able containing the number of event name and even- "Event— count" is a signed 4-byte binary variable in 

t— key pairs of interest which is returned the number of the specified even- 
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t name and event— key pairs for which signals must be 
bound to the monitor for the monitored condition to be 
considered satisfied. 

"Present— event—count" is a signed 4-byte binary 
variable in which is returned the number of the speci- 
fied event—name and event—key pairs for which signals 
are currently bound to the event monitor. 

"Trap— routine address" is a 4-byte binary variable 
in which is returned the address of a routine to be in- 
voked when the condition defined by the monitor is 
satisfied, as established by the EventTrap function. If no 
address has been established by EventTrap, a value of 0 
is returned. 

"Trap— routine name" is an 8-byte variable in which 
is returned the name of a routine to be invoked when 
the condition defined by the monitor is satisfied, as 
established by the EventTrap function, or blank if no 
event trap is associated with the monitor. 



tokens array, and "vm_ evn_select— on" means start 
monitoring of the monitor identified by the correspond- 
ing element of the monitor—tokens array. 
EventQuery — An application program can call this 

5 function to obtain information about an existing event 
definition, including a list of all event monitors defined 
in the current process which are sensitive to occur- 
rences of the event The EventMonitorQuery function 
may be used to obtain further information about a par- 

10 ticular event monitor. 



EventQuery 



15 



EventMonitorReset 



retcode 
rsncode 
monitor_token 



20 



Parameters 

"EventMonitorReset" is the name of the function 
being invoked. 

"Retcode" is a signed 4-byte binary variable to hold 
the return code from EventMonitorReset 



25 



retcode 

rsncode 

event name 

event name length 

event—flag 

event— flag— size 

event— flag count 

loose— signal— limit 

signal timeout— period 

loose— signal— count 

event selection_mask 

event— enablement mask 
monitor— token 
monitor— tokeo_size 
monitor_token count 



"Rsncode" is a signed 4-byte binary variable to hold 30 voked. 



Parameters 

"EventQuery" is the name of the function being in- 



the reason code from EventMonitorReset. 

"Monitor—token" is a signed 4-byte binary variable 
containing the token that identifies the monitor whose 
state is to be reset A value of 0 may be used to identify 
the active event monitor most recently activated on the 35 
current thread. 



EventMonitorSelect 



retcode 
rsncode 

number— of— monitors 
monitor_tokens 
monitor—selection— masks 
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Parameters 45 

"EventMonitorSelect" is the name of the function 
being invoked. 

"Retcode" is a signed 4-byte binary variable to hold 
the return code from EventMonitorSelect 

"Rsncode" is a signed 4-byte binary variable to hold 50 
the reason code from EventMonitorSelect. 

"Number— of— monitors" is a signed 4-byte binary 
variable containing the number of monitor— tokens of 
interest 

"Monitor— tokens" is an array of number— of— moni- 55 
tors 4-byte binary variables each element of which con- 
tains the token of the monitor which is to be selected on 
or off. A value of 0 may be used to identify the active 
event monitor which was most recently activated on 
the current thread. 60 

"Monitor— selection masks" is an array of num- 
ber— of— monitors signed 4-byte binary variables each 
element of which contains the selection mask for the 
monitor identified by the corresponding element of the 
monitor— tokens array. The value of the selection mask 65 
determines the action to be performed, i.e. "vm— ev- 
il— select— off" means stop monitoring of the monitor 
identified by the corresponding element of the monitor 



"Retcode" is a signed 4-byte binary variable to hold 
the return code from EventQuery. 

"Rsncode" is a signed 4-byte binary variable to hold 
the reason code from EventQuery. 

"Event name" is a character variable which con- 
tains the name of the event to be queried. 

"Event name—length" is a signed 4-byte binary vari- 
able containing the length of event name. 

"Event—flag" is an array of signed 4-byte binary 
variables in which is returned information about how 
the event is managed. Exactly one option from each of 
the following sets is included. 

The scope of the event name is indicated either by 
"vm—evn— process— scope" which means the desig- 
nated process, or "vm—evn— session—scope" which 
means the designated session. 

The manner in which an event signal is propagated to 

multiple event monitors is indicated by "vm—evn 

broadcast— signals" which means broadcast "vm_ ev- 
n fifo— signals" which means FIFO sequence, or 
"vm—evn— lifo— signals" which means LIFO sequence. 

The treatment of the signaler is indicated by "vm 

evn async— signals" which means that the signaling 
thread is allowed to continue executing (the default), 
"vm—evn— sync— thread signals" which means that 
the signaling thread is suspended to await the outcome 
of event processing, or "vm—evn— sync— process sig- 
nals" which means that all threads in the signaling pro- 
cess, with the exception of those threads running as the 
result of a monitor activated by this signal, are sus- 
pended to await the outcome of event processing. 

"Event— flag— size" is a signed 4-byte binary variable 
containing the number of elements in the event— flag 
array. 

"Event—flag count" is a signed 4-byte binary vari- 
able in which is returned the number of elements in the 
event—flag array which have been set by EventQuery. 
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"Loose— signal -limit" is a signed 4-byte binary van- -continued 
able in which is returned the number of event signals 



which may be retained if no eligible event monitor even t „ n ame-addjess, 

• . A ' , ^ , . , - , • . event name length 

exists to which to bind the signal or if a process is not actual_name_Jength, 

monitoring for the event at the time the event is sig- 5 monitor—token 

naled. When the limit is exceeded, the oldest loose sig- monitor-token sir e 

nal is discarded to make room for the newest arrival. A monitor-token-cotmt 

value of 0 indicates that no loose signals are retained. A 
value of negative one (— 1 ) means that the loose signal 

set is allowed to grow without limit, subject to the W Parameters 

availability of virtual storage. "EventQueryAll" is the name of the function being 

"Signal timeout—period" is a signed 4-byte binary invoked, 

variable in which is returned the maximum length of "Retcode" is a signed 4-byte binary variable to hold 

time, specified in microseconds, that a signaling thread the return code from EventQueryAll. 

is allowed to remain suspended awaiting the completion 15 "Rsncode" is a signed 4-byte binary variable to hold 

of processing of the signal. A value of 0 indicates that the reason code form EventQueryAll. 

the signaling thread waits indefinitely for the comple- "Number— of— events" is a signed 4-byte binary vari- 

tion of signal processing. If the option specifying that able containing the number of elements in the following 

the signaling thread is to continue processing is in- three arrays. 

eluded in the event—flag array, then this parameter is 20 ''Event— name— address" is an array of num- 

meaningless. ber— of— events 4-byte pointer variables each element of 

"Loose s ign al c ount" is a signed 4-byte binary vari- which contains the address of a character variable in 

able in which is returned the number of loose signals which is to be returned the name of a defined event 

currently being retained for the specific event. "Event— name— length" is an array of number— of— e- 

"Event— selection— mask" is a signed 4-byte binary 25 vents signed 4-byte binary variables, each element of 

variable in which is returned the state of the event selec- which contains the length of the buffer of the corre- 

tion mask; i.e. "vm~ evn_ select— off" which means not spending element of the event— name— address array. If 

monitoring for even t nam e, or "vm_ evn_select_ on" the name is longer than the buffer, it is truncated; if 

which means monitoring for event nam e. shorter, the excess space at the end of the buffer is un- 

"Event— enablement— mask" is a signed 4-byte binary changed, 

variable in which is returned the state of the event en- "ActuaL_name_ length" is an array of num- 

ablement mask; i.e. 'Vm evn disable" which means dis- ber_of_events signed 4-byte binary variables. This 

abled for event— name, or "vm-evn_enable" which function uses this array to output the lengths of the 

means enabled for event— name. The event selection event names pointed to by the corresponding element of 

and enablement masks are maintained on a process basis the event— name— address array, 

and are reported for the issuing process only. ,( Monitor_token" is an array of signed 4-byte binary 

"Monitor-token" is an array of signed 4-byte binary variables in which is returned the list of tokens identiry- 

yanables in which is returned the list of tokens identify- mg ^ ^ e event monitors defined in the current pro- 

ing the event monitors defined in the current process ^ cess< 

which are sensitive to the specified event For events "Monitor_token_size" is a signed 4-byte binary vari- 

defined as sequential, the tokens are output in the order able containing the number of elements in the 

in which they will be processed. For events defined as m0 nitor_token array that are available to be filled in. 

broadcast, the tokens are output in the order in which "Monitor-token-count" is a signed 4-byte binary 

the monitors were created. 4f . variable m which & returned the total number of event 

*Momtor_ token— size is a signed 4-byte binary vari- monitors defmed m ^ current process . if 

able containing the number of elements m the m0 nitor^token_count is not greater than 

momtor token array which are available to be ruled in. mon itor_token_size, then the first monitor-token-. 

Momtor-token-count is a signed 4-byte binary ^ elements of the monitor-token array contain the 

variable in which is returned the total number of event 50 tokens ^ identif y ^ ^ ^ of monitors ^ ^ 

momtorsdefm^ remainder of the array is unchanged. Otherwise, only 

tive to the specified event If momtor-token_count is ^ ^ m omtor-tok«i^i2e monitor tokens are re- 

not greater than momtor— token— size, then the first turned 
monitor— token— count elements of the monitor— token 

array contain the tokens which identify that entire set of 55 

monitors and the remainder of the array is unchanged; EventRetrieve retcode 

otherwise, only the first monitor—token— size monitor rsncode 

tokens are returned. monitor-token 

EventQueryAll— An application program can call datalbuffer 

this function to obtain the names of all events and the ^ data— buffer— length 

tokens for all event monitors visible to this process. The even t d ata l ength 

EventQuery and EventMonitorQuery functions may be ! 
used to obtain further information about events and 

event monitors. Parameters . 

65 "EventRetrieve" is the name of the function being 

EventQueryAll retcode, "V?**- 

rsncode, Retcode" is a signed 4-byte binary variable to hold 

number— oL_events the return code from EventRetrieve. 
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"Rsncode" is a signed 4-byte binary variable to hold , 

the reason code from EventRetrieve. -continued ■ 

"Monitor—token" is a signed 4-byte binary variable nncode 

containing the token which identifies the monitor from wratl^Llength 

whose current signal set the retrieval is to be performed. 5 event-data 

A value of 0 may be used to identify the active event event data length 

monitor which was most recently activated on the cur- event_iey_offset 

rent thread. event-Jcey_length 

"Index" is a signed 4-byte binary variable identifying, 
as an index into the event-name address, even- 10 Parameters 
t n a m e l ength, events-key address, and even- 

t__key_length arrays specified in the creation of the "EventSignal" is the name of the function being in- 
event monitor, _ the event name and event—key pair voked. 

corresponding to the signal from which the data is to be "Retcode" is a signed 4-byte binary variable to hold 
retrieved. 15 ^ e return code from EventSignal. 

"Data—buffer" is a character variable in which is "Rsncode" is a signed 4-byte binary variable to hold 
returned the signaled data for the event-name and the reason code from EventSignal. 
event— key pair identified by index. "Even t - n a m e" is a character variable which con- 

"Data-buffer_length" is a signed 4-byte binary van- tams ^ name of ^ event whose occurrence is to be 
able containing the defined length of data— bufTer. 20 ste^^- 

"Event-_data_iength" is a signed 4-byte binary van- "Event-name-length" is a signed 4-byte binary vari- 
able in which is returned the length of the signaled data ^Jf containin S length of event-name, 
for the event— name and event-key pair identified by "Event— data" is a character variable which contains 
index. If event_data_length is greater than data_buf- ***** to made available to any interested event moni- 
fer—length, the signaled data is truncated on the right 25 to ^f' 

and a warning return code is generated. Event_data_ length" is a signed 4-byte binary vari- 
able key giving the length of event-data. 

"Event-key— offset" is a signed 4-byte binary vari- 

EventSdect retcode able which contains the offset in event— data of the first 

rsnc ? te , 30 hyte of a key that characterizes the particular instance 

of the event to be signaled. 
event-name_iength Event— key-length" is a signed 4-byte binary vari- 

event— selection— mask able which contains the length of the key contained in 

: event— data. The key may be null (that is, its length may 
35 be 0) if no secondary characterization of the event is 
Parameters necessary for this type of event or for this occurrence of 

"EventSelect" is the name of the function being in- the event 
voked. 

"Retcode" is a signed 4-byte binary variable to hold EventTest retcode 

the return code from EventSelect 40 rsncode 

"Rsncode" is a signed 4-byte binary variable to hold monitor_token 
the reason code from EventSelect. eTt^ 0 * - *™* 

"Number— of_events" is a signed 4-byte binary vari- ~~ — — ^— 

able containing the number of events of interest. 

"Event-name-address" is an array of num- 45 Parameters 
ber—of— events 4-byte pointer variables each element of 

which contains the address of the name of an event "EventTest" is the name of the function being in- 
whose signals are to be selected on or off. voked. 

"Event-name— length" is an array of number— of— e- "Retcode" is a signed 4-byte binary variable to hold 
vents signed 4-byte binary variables each element of 50 to© ret™* code from EventTest. 
which contains the length of the event— name pointed to "Rsncode" is a signed 4-byte binary variable to hold 
by the corresponding element of the event_name__ad- ^ reason code from EventTest. 
dress array. "Monitor— token" is a signed 4-byte binary variable 

"Event-selection— mask" is an array of num- containing the token which identifies the monitor 
ber—of— events signed 4-byte binary variables each 55 whose condition is to be tested. A value of 0 may be 
element of which contains the selection mask of the use ? i to * dentu< y the active event monitor most recently 
event— name pointed to by the corresponding element activated on the current thread, 
of the event_name— address array. The value of the "Number— of— events" is a signed 4-byte binary van- 
selection mask determines the action to be performed, ***** containing the number of events whose occurrence 
i.e. "vm— evn-select-off' which means stop monitor- 60 * t0 tested - general, this should be the same as the 
ing of the event— name pointed to by the corresponding number of even t nam e and event— key combinations 
element of the event-name— address array, or "vm_ ev- specified in the definition of the event monitor. 
n_ select-on" which means start monitoring of the . " Event — flag" is an array of number_of— events 
event-name pointed to by the corresponding element signed 4-byte binary variables in each element of which 
of the event— name— address array. 65 ^ returned an indication of the occurrence or non- 

occurrence of the event identified by the event— name 

and event— key pair specified by the corresponding 

EventSignal mcode elements of the event— name— address, even- 
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t name length, event key— address, and even 
t_-key_length arrays used in defining the event moni- 
tor, i.c 



36 



0, 1, 2, . . . 


indicates that the event has been signaled, 




the number is the length of data provided on 




the signal that may be obtained with the 




EventRetrieve function. 


-1 


indicates that the event has not been 




signaled, 


-2 


indicates that the event definition has been 




deleted, and 


-3 


indicates no corresponding event name and 




event key pair was defined in the event 




monitor. 



10 



15 


Event Trap 


retcode 






csncode 






monitor—token 


20 




trap—routine address 




trap—routine— name 





Parameters 



25 



"Rsncode" is a signed 4-byte binary variable to hold 
the reason code from EventWait. 

"Monitor—token" is a signed 4-byte binary variable 
containing the token which identifies the monitor 
whose condition is to be awaited. The monitor must not 
already be in the waiting state; there may be no more 
than one wait outstanding to a monitor at a time. A 
value of 0 may be used to identify the active event 
monitor which was most recently activated on the cur- 
rent thread. 

*'Number_jo£_jevents" is a signed 4-byte binary vari- 
able containing the number of events whose occurrence 
is to be indicated when the EventWait function com- 
pletes. In general, this should be the same as the number 
of event— name and event— key combinations specified 
in the definition of the event monitor. 

"Event— flag" is an array of number— of— events 
signed 4-byte binary variables in each element of which 
is returned an indication of the occurrence or non- 
occurrence of the event identified by the event—name 
and event— key pair specified by the corresponding 
elements of the event name address, even- 
t—name—length, event-key— address, and even- 
t—key—length arrays used in defining the event moni- 
tor, i.e. 



"EventTrap" is the name of the function being in- 
voked. 

"Retcode" is a signed 4-byte binary variable to hold 
the return code from EventTrap. 

'•Rsncode" is a signed 4-byte binary variable to hold 30 
the reason code from EventTrap. 

"Monitor—token" is a signed 4-byte binary variable 
containing the token that identifies the monitor whose 
condition is to be trapped. A value of 0 may be used to 
identify the active event monitor that was most recently 35 
activated on the current thread. 

'Trap—routine— address" is a 4-byte binary variable 
containing the address of the routine to be invoked 

when the condition defined by the monitor is satisfied. % . , ^ . * 

T - « j , J ac\ lowing manner when the events are trace events. As 

If an address was previously associated with the event 40 v -r . Z ^ r- . A , - , j , 

_ . \ . j * ~T noted above, each event definition mcludes a loose 



0, 1, 2, . . . indicates that the event has been signaled, 

the number is the length of data provided on 
the signal that may be obtained with the 
EventRetrieve function. 

— 1 indicates that the event has not been 

signaled, 

—2 indicates that the event definition has been 

deleted, and 

— 3 indicates no corresponding event— name and 
event— key pair was defined in the event monitor. 



The event management services described above can 
be used to establish and process trace tables in the fol- 



monitor, it is automatically replaced by the new 
trap— routine address. If the address is a non-zero 
value, the trap— routine— name parameter is meaning- 
less. 

"Trap— routine— name" is a 8-byte character variable ^ 
containing the name of the routine to be invoked when 
the condition defined by the monitor is satisfied. This 
parameter has meaning only if the trap—routine— ad- 
dress parameter is zero. If a name was previously associ- 
ated with the event monitor, it is automatically replaced 
by the new trap— routine— name. If the trap— routi- 
ne— address parameter is zero and the trap— routine 

name is blank, the trap associated with the specified 
event monitor is cancelled. 
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EventWait 



retcode 
rsncode 

monitor— token 
number— of_ events 
event—flag 



Parameters 

"EventWait" is the name of the function being in- 
voked. 

"Retcode" is a signed 4-byte binary variable to hold 
the return code from EventWait 



signal limit which specifies a maximum number of event 
signals which can be stored, tied to the event definition 
in loose signal set 41 when there is no interested event 
monitor (which is selected-on). When the loose signal 
limit is reached, each subsequent event signal is stored 
at the expense of the oldest event signal; the newer 
event signals generally provide more important trace 
information. Therefore, the loose signal set can be used 
as a trace table, or a "pool" of event signals for a subse- 
quently defined event monitor by delaying definition of 
an interested event monitor. When a process is inter- 
ested in processing the trace event signals, the process 
defines an event monitor which is interested in the event 
55 and calls the EventWait function, EventTrap function 
or EventTest function. As a result of the creation of the 
event monitor, the loose signals for the event(s) of inter- 
est to the event monitor will be transferred to the bound 
signal set of the event monitor as described above with 
60 reference to FIG. 17. If there are enough of these sig- 
nals to satisfy the event monitor, then the event monitor 
will establish the current signal set in response to the 
call to the EventWait function, EventTrap function, or 
EventTest function, and the event handler within the 
65 associated process can access the event signals within 
the current signal set 

Thus, the loose signal set of one or more event defini- 
tions can be accessed by interested event handlers ac- 



03/18/2004, EAST version: 1.4.1 



cording to their specific requirements by subsequently 
defining appropriate event monitors. Also, each event 
handler can access the trace table in real time, i.e., upon 
request, and can process the trace data directly from the 
current signal set (without having to access any external 5 
storage device such as a Direct Access Storage 
Device— DASD). 

The transfer from the loose signal set to the bound 
signal set can be controlled in different ways using the 
foregoing functions. If an event monitor interested in all 10 
trace signals is created without first selecting the event 
off, all the loose signals within the loose signal set for 
that event will be transferred to the event monitor and 
then the loose signal set will be entirely depleted. As a 
result, if a second interested event monitor is subse- 15 
quently defined, these loose signals will not be available 
to the second interested event monitor. However, if two 
or more event monitors need a copy of the loose signal 
set, then the following procedure can be utilized to 
provide the loose signals to all the event monitors. The 20 
event of interest is first selected-off by a call to the 
EventSelect function (step 254 of FIG. 14), which will 
then mark the event definition as "selected-off*. Next, 
the event monitors are defined, and afterwards, the 
event is selected-on by another call to the EventSelect 25 
function (step 266 of FIG. 14). In response, the Event- 
Select function will mark the event definition as select- 
ed-on (step 268) and identify all event monitors which 
are interested in the event by reading the event monitor 
definitions (step 270). Next, the EventSelect function 30 
will transfer copies of all loose signals to all such inter- 
ested event monitors if the broadcast mode has been 
designated in the event definition (and erase the loose 
signal set), or transfer all the loose signals to the first 
event monitor in the sequence if the propagation mode 35 
has been designated in the event definition (and erase 
the loose signal set) (step 272). 

Also as noted above, each event monitor definition 
includes a bound signal limit and a satisfaction level for 
each event of interest to the event monitor. The bound 40 
signal limit for each event indicates the maximum num- 
ber of event signals for the event that can be stored 
bound to the event monitor. When the next event signal 
for this event type is received, it is stored at the expense 
of the oldest event signal for the same type of event. 45 
The bound signal limits for different events of interest to 
the same event monitor can vary. The satisfaction level 
for each event indicates the number of occurrences of 
the event required to permit the event monitor to pro- 
vide the associated event handler with the event signals 50 
from the current signal set. The satisfaction levels for 
different events of interest to the same event monitor 
can vary. Only when the satisfaction levels are met for 
all events is the event handler permitted to access the 
current signal set Any number of event monitors can be 55 
defined, and the definitions can reference the same, 
different or partially overlapping sets of event types. 
One event or set of events can be of interest to multiple 
event monitors. Each application program can specify 
its own parameters for its event monitor or monitors, 60 
i.e. event types of interest, bound limits, and satisfaction 
levels. Also, each application program can control its 
own trace table with calls to the EventDelete function 
69, EventEnable function 44, EventModify function 71, 
EventMonitorDelete function 68, EventMonitorEnable 65 
64, and EventMonitorSelect function 66. Such control, 
as well as the creation of the event monitor, can be 
made at any time, i.e. dynamically. 
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Therefore, as an alternative to utilizing the loose 
signal set as a trace table or a pool for a subsequently 
defined event monitor, the event monitors can be de- 
fined before occurrences of the event(s) of interest, and 
used directly to provide the trace table. The bound 
limits establish the "wrap sizes" and the satisfaction 
levels establish the number of signals of each type to be 
made available to the event handler upon request In 
this configuration, if the event handler calls the Event- 
Trap or EventWait function before the event monitor is 
satisfied, then the event handler can access the trace 
table (current signal set) in real time, Le. as soon as the 
event monitor satisfied. Also, when the current signal 
set is established and the event handler accesses the 
current signal set, the current signal set is erased to 
make room for new event signals in the bound signal 
set While this alternate arrangement provide some 
advantages over the use of the loose signal set as a trace 
table or pool, the alternate arrangement may require a 
somewhat higher operating system overhead when 
multiple event monitors are interested in the same event 
because all event signals in the alternate arrangement 
are transferred to the bound signal set of all event moni- 
tors, even those in excess of the loose signal limit. In 
contrast, in the other arrangement which utilizes the 
loose signal set as a trace table or pool, the maximum 
number of event signals that require the overhead of 
subsequent transfer to an event monitor is the loose 
signal limit 

To facilitate and ensure proper establishment, man- 
agement, and use of the trace tables, the following addi- 
tional trace management services including an applica- 
tion program interface are provided. The trace manage- 
ment services are controlled by ITRACE and 
ETRACE keyboard commands, or a TRACECON- 
TROL call. The TRACECONTROL call defines 
which trace events of a predeterrnined set should be 
signalled and the attributes of the signalled trace events, 
as well as provide some additional trace processing 
options. The TRACECONTROL call is - made to a 
conversational monitor system (CMS) portion of oper- 
ating system 11. Many of the standard functions of the 
conversational monitor system portion of operating 
system 11 are described in a publication entitled 
VM/ESA CMS Application Development Reference, 
published June 1990 by IBM Corp. of Armonk, N.Y. 
IBM order number SC24-5451-00. The format for the 
TRACECONTROL call is as follows: 



TRACECONTROL Rtncode 
Rsncode 
Traceflg 
Wrapsize 
Function 
N 

Tracetype(N) 

Tracetype-JSetting(N) 



Parameters 

"Rtncode" is a signed 4-byte binary variable to hold 
the return code from TRACECONTROL. 

"Rsncode" is a signed 4-byte binary variable to hold 
the reason code from TRACECONTROL. 

"Traceflg" specifies to what degree the signaller of a 
trace event is to be synchronized. It is a signed four byte 
binary integer with valid values as follows: 
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0 (ASYNC) signalling thread continues processing 

independently of event processing. 

1 (TSYNC) signalling thread is suspended to await 

outcome of event processing. 

2 (PSYNC) signalling process is suspended to await 

outcome of event processing. 

3 (DSYNQ signalling process and all its 

descendants are suspended to await the 
outcome of event processing. 
—1 (UNCH) synchronization is unchanged. 



10 



"Wrapsize" specifies how many trace events are re- 
tained if no eligible trace event monitor exists at the 
time the event is signalled. This corresponds to the 
loose signal limit. When the wrapsize is exceeded, the 15 
oldest trace event is discarded to make room for the 
newest arrival. This is a four byte signed binary integer. 
A value of 0 indicates that no trace events are to be 
retained. A value of — 1 indicates that trace events will 
continue to be retained until virtual storage is ex- 20 
hausted. A value of —2 indicates the wrapsize is to 
remain unchanged. Any other negative value is invalid. 

"Function" specifies the use of the arrays to follow. It 
is a four byte signed binary integer with valid values as 
follows: 



25 



The TRACECONTROL call always results in an 
event definition of session scope and broadcast signals. 
If the signalling thread does not continue independently 
of the event processing, the suspended thread will wait 
indefinitely, i.e. there is no timeout period. The trace- 
type and tracetype—setting arrays are processed in 
array order. For example, if values corresponding to 
ALL and OFF are the first elements in the respective 
arrays, all trace categories are set off before processing 
subsequent elements in the arrays. As a result, in gen- 
eral, an array element may be nullified by a subsequent 
array element. CMS will invoke the TRACECON- 
TROL routine with the following parameter settings as 
part of its initialization — Function = ITRACE, Tracefl- 
g= ASYNC, Wrapsize = determined from DMSNGP, 
N=l, Tracetype =ALL, and Tracetype— Setting- 
= ON. These settings are set before the system profile is 
executed and thus may be overridden by the system 
profile. 

The ITRACE keyboard command is similar in effect 
to the TRACECONTROL API call, and specifies 
which of the predefined, trace events are selected for 
signalling by CMS to the event signal manager, and the 
"wrap size" or the loose signal limit The format is as 
follows: 



0 (QUERY ITRACE) The ITRACE tracetypes are 

queried and their setting is returned 
in the tracetype— settings array. 

1 (QUERY ETRACE) The ETRACE tracetypes are 

queried and their setting is returned 
in the tracetype— settings array. 

2 (ITRACE) The tracetypes and 

tracetype— settings are used as a 
callable interface to the ITRACE 
command. 

3 (ETRACE) The tracetypes and 

tracetype—settings are used as a 
callable interface to the ETRACE 
command. 

-1 (UNCH) Indicates that the follows arrays 
are to be ignored. 



ITRACE 




ALL 


ON/OFF 


COMMUNICATION 


ON/OFF 


DISPATCH 


ON/OFF 


STORAGE 


ON/OFF 


I/O 


ON/OFF 


PROGMAN 


ON/OFF 


PROCMAN 


ON/OFF 


DATAMAN 


ON/OFF 


MISC 


ON/OFF 


GROUP 


ON/OFF 


END 




WRAPSIZE 


xxxxxxxx 



"All" specifies whether or not all trace entries will be 
signalled. Permissible values are: 



"N" Specifies the number of trace types to be set. It 
is a four byte signed binary integer. 

'Tracetype" Specifies the trace types to be set. It is 
an array of 4-byte signed binary integers with the fol- 
lowing valid values: 



0 (ALL) 


All trace types 


1 (COMM) 


CntTimnnirat^n" events 


2 (DISP) 


Dispatch events 


3 (STOR) 


Storage Management events 


4 (K>) 


I/O events 


5 (PRGMAN) 


Program Management events 


6 (PRCMAN) 


Process Management events 


7 (MISC) 


Timer, externa] interrupt and 




machine check events 


8 (DTMAN) 


Data Management events 


9 (GROUP) 


Previous settings are for all 




machines in the virtual machine 




group. 
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•Tracetype—Setting" Specifies the settings corre- 
sponding to the trace type array. It is an array of 4-byte 
signed binary integers with the following valid values: 

65 

0 (OFF) Corresponding trace type is set OFF. 

1 (ON) Corresponding trace type is set ON. 



ON trace entries are signalled. 

OFF trace entries are not signalled. 



"Communication" specifies whether or not commu- 
nication trace entries will be signalled. Possible exam- 
ples of this type of trace entry are IUCV and APPC 
transactions and queue operations. Permissible values 
are: 



ON trace entries are signalled. 

OFF trace entries are not signalled 



"Dispatch" specifies whether or not dispatch trace 
entries will be signalled. Possible examples of this type 
of trace entry are Thread Dispatch and Thread Priority 
Modification. Permissible values are: 



ON trace entries are signalled. 

OFF trace entries are not signalled. 

"Storage" specifies whether or not storage trace 
entries will be signalled. Possible examples of this type 
of trace entry are Free Storage Obtain and Free Storage 
Return. Permissible values are: 
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ON 
OFF 



trace entries are signalled. 
trace entries are not signalled 



"I/O" specifies whether or not I/O trace entries will 
be signalled. Possible examples of this type of trace 
entry are requests for I/O and I/O interrupt occur- 
rences. Permissible values are: 



10 



ON 

OFF 



trace entries are signalled. 
trace entries are not signalled. 



"Progman" specifies whether or not program man- 
agement trace entries will be signalled. Possible exam- 
ples of this type of trace entry are Command Load and 
Program Load. Permissible values are: 



15 



ON 
OFF 



trace entries are signalled, 
trace entries are not signalled. 
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"Procman" specifies whether or not process manage- 
ment trace entries will be signalled. Possible examples 
of this type of trace entry are Process Create and 
Thread Create. Permissible values are: 
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ON 
OFF 



trace entries are signalled, 
trace entries are not signalled. 
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"Dataman" specifies whether or not data manage- 
ment trace entries will be signalled. Possible examples 
of this type of trace entry are File System Read and File 
System Write. Permissible values are: 



35 



ON 
OFF 



trace entries are signalled, 
trace entries are not signalled. 



"Misc" specifies whether or not trace entries not 
lending themselves to categorization will be signalled. 
Possible examples of this type of trace entry are ma- 
chine checks, external interrupts and timer interrupts. 
Permissible values are: 
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ON 
OFF 



trace entries are signalled. 
trace entries are not signalled. 
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"Group" specifies whether or not trace entries to be 
signalled are signalled in all machines in the issuer's 
virtual machine group. This operand applies only to 

those trace entries currently being signalled when the rr 

GROUP operand is processed. That is, operands to the 55 function to establish an event monitor wmcVk^mter- 



"Wrapsize xxx" specifies how many trace entries are 
retained in the trace table if no eligible trace event mon- 
itor exists at the time the trace entry is signalled. When 
the wrapsize is exceeded, the oldest trace entry is dis- 
carded to make room for the newest arrival. A value of 
0 indicates that no trace entries are to be retained. 

The ETRACE command specifies which of the se- 
lected trace events should be sent to a predetermined 
event handler within a control program of the operating 
system 11 for the purpose of recording the event signals 
in a spool file. The control program provides many 
standard functions as described in a publication entitled 
VM/ESA Diagnostics Guide for 370, published by 
IBM Corp of Armonk N.Y. in June 1990, IBM order 
number LY24-5242-00. The format for the ETRACE 
command is as follows: 

ETRACE EVENTNAME ON OR OFF, 
EVENTNAME ON OR OFF ETC. 

The steps involved in utilizing the trace management 
services are as follows: 

First, an application program issues the TRACE- 
CONTROL call or a user enters the ITRACE com- 
mand through the keyboard to define which trace 
events will be built and signalled, as well as the wrap 
size. Next, the trace events occur at appropriate points 
in the processing of CMS, and CMS, which serves as a 
signaller, signals the trace events including the event 
data. The format for the trace entries is as follows: 

1. HEADER LENGTH— Length of the trace header 
information. 

2. USERID — Userid of the virtual machine issuing 
the trace signal. 

3. PROCESSID— Unique process identifier of the 
process on whose behalf this trace entry is being 
signalled. 

4. THREADID — Unique thread identifier of the 
thread on whose behalf this trace entry is being 
signalled. 

5. TRACEID — The specific type of trace entry. 

6. HMESTAMP — Time at which the trace entry is 
being signalled (in timer units). 

7. FORMAT ROUTINE— Identifier of routine that 
is needed to format this trace entry. 

8. VARIABLE HEADER DATA— Other data 
which may be included in the header. 

9. DATA LENGTH— Length of actual trace data. 

10. VARIABLE DATA— Actual trace data. 
As long as no event monitors are interested in the 

trace events, the maximum number of trace event sig- 
nals which are stored is equal to the wrap size, and these 
trace events are stored in the loose signal set. Next, a 
user application program calls the EventMonitorCreate 



right of the GROUP operand are not affected by the 
GROUP operand. This operand may not be specified 
by virtual machines which are not part of a group. 
Permissible values are: 
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ON trace entries are signalled in all 

machinr* in the virtual machine group. 

OFF trace entries are not signalled in any 

other machinr in the virtual machine 

group. 



"End" specifies that no trace entries are to be sig- 
nalled. 
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ested in the event. The EventMonitorCreate call can 
include specification of a limiting key to limit the inter- 
est of the event monitor. In this scenario, only the first 
event monitor which is established having interest in the . 
event will receive the content of the loose signal set. 
Alternately! as noted above, the event can be selected 
off before two or more event monitors are created to 
provide copies of the loose signal set to the two or more 
event monitors. Next, the user application program 
calls the EventWait or EventTrap function to obtain 
the current signal set when the event monitor is satis- 
fied. The user application program is notified upon 
satisfaction of the event monitor and can call the Even- 
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10 



15 



tRetrieve function to read the contents of the current 
signal set and then process the event data. 

It should be understood that even though the forego- 
ing trace management services and application program 
interface refer to a virtual machine environment, they 
are useful in other environments. 

FIGS. 18 and 19 are flowcharts illustrating an exam- 
ple of usage of the trace management services and appli- 
cation program interface to trace (for trouble shooting 
purposes) which program threads in a multitasking 
operating system have been executed (for trouble shoot- 
ing purposes) and the time of execution for each thread. 
FIG. 18 illustrates the actual trace management services 
and API which are involved in this function. In step 
500, the operating system creates an event named 
"Trace" by a call to the EventCreate function 40. Next, 
the user application program issues a TRACECON- 
TROL call and specifies a Dispatch type of event as a 
parameter in the call (step 506). The operating system 
reads the Dispatch parameter from the call (step 508), 20 
and then notifies the dispatcher to signal the Dispatch 
event (step 510). The dispatcher is the function that 
selects program threads for execution by CPU 19. 

FIG. 19 is the flowchart for the dispatcher referenced 
in FIG. 18. In step 530, the dispatcher removes an old 25 
thread from the CPU and starts execution of a new 
thread. To provide event data to accompany the trace 
event signal, the dispatcher reads the current time (with 
a clock not shown) (step 532), and stores this current 
time as being the time that the new thread started and 30 
the old thread halted execution (step 534). The dis- 
patcher then computes the old thread's CPU execution 
time as the difference between the current time and the 
start time for the old thread which was previously 
stored (step 536). Next, the dispatcher calls the Event- 35 
Signal function and provides the following event data: 
old thread ID, old thread CPU usage time, and new 
thread ID (step 540). 

What is claimed is: 

1. A process for managing events in a computer sys- 
tem, said process comprising the steps of: 

dynamically introducing by a program during normal 
operation of the computer an unlisted event type 
and storing a definition of the event type, said defi- 
nition specifying a maximum number of event sig- 45 
nals to be stored in the absence of a program which 
is interested in receiving notification of the event 
type; 

receiving signals of occurrences of said event; 

in the absence of a program which is interested in said 50 
event, storing the event signals in association with 
said event definition but limited by said maxim um 
number in said event definition; 

subsequent to the event signal storing step, establish- 
ing an interest by a program in said event by defin- 55 
ing an event monitor for said program, said defini- 
tion specifying a maTimnm number of event signals 
to be stored; and 

after the establishing step, transferring the stored 
event signals to said event monitor but limited by 60 
said maximum number in said event monitor defini- 
tion; said maximum number in said event monitor 
definition can be different from said maximum 
number in said event definition. 

2. A process as set forth in claim 1 further comprising 65 
the step of notifying the interested program of the oc- 
currence of said event upon request by said program to 
said event monitor. 



3. A method for managing events, said method com- 
prising the computer implemented steps of: 

dynamically introducing to a computer by a program 
during normal operation of the computer an un- 
listed event type and storing an indication of the 
event type; 

subsequently receiving by the computer a signal of an 
occurrence of said event type; and pursuant to the 
stored event type indication and receiving step, 
storing the event signal. 

4. A method for managing events, said method com- 
prising the steps of: 

dynamically introducing to a computer by a program 
during normal operation of the computer an un- 
listed event type and storing an indication of the 
event type; 

subsequently receiving by the computer a signal of an 

occurrence of said event type; 
pursuant to the stored event type indication and re- 
ceiving step, storing the event signal; and 
handling the event in response to the event signal, and 
wherein the event is handled without interrupting 
the computer. 

5. A method as set forth in claim 3 further comprising 
the step of handling the event in response to the event 
signal, and wherein the event is handled in real time 
after being stored. 

6. A computer for managing events, comprising: 
means for dynamically introducing to the computer 

by a program during normal operation of the com- 
puter an unlisted event type and storing an indica- 
tion of the event type; 
means for subsequently receiving by the computer a 

signal of an occurrence of said event type; and 
means, responsive to the stored event type indication 
and event signal, for storing the event signal. 

7. A computer as set forth in claim 6 further compris- 
ing means for handling the event in response to the 
event signal, and wherein the event is handled during 

40 normal operation of the computer. 

8. A computer as set forth in claim 6 further compris- 
ing means for handling the event in response to the 
event signal, and wherein the event is handled in real 
time after being stored. 

9. A method for managing events, said method com- 
prising the following computer implemented steps in 
order: 

dynamically introducing to a computer by a program 
during normal operation of the computer an un- 
listed event type and storing an indication of the 
event type; 

receiving a signal of an occurrence of said event type; 
in the absence of a program which is interested in 
receiving notification of said event type, storing 
the event signal in association with the stored event 
type indication; 
dynamically defining by a program during normal 
operation of the computer an event monitor within 
said computer; 
transferring the stored event signal to said event mon- 
itor, and 

transferring the event signal from the event monitor 
to said program during normal operation of the 
program. 

10. A method as set forth in claim 9 wherein the event 
signals are transferred from the event monitor to the 
program upon request by the program. 

11. A computer for managing events, comprising: 
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means for dynamically introducing to the computer 
by a program during normal operation of the com- 
puter an unlisted event type and storing an indica- 
tion of the event type; 

means, responsive to a signal of the event and the 
absence of a program which is interested in receiv- 
ing notification of said event type, for storing the 
event signal in association with the stored event 
type indication; 

means for dynamically receiving from a program 
during normal operation of the computer after 
storage of the event signal a definition of an event 
monitor for said event type; 

means for transferring the stored event signal to said 
event monitor; and 

means for transferring the event signal from the event 
monitor to the program during normal operation of 
the program. 

12. A computer as set forth in claim 11 wherein: 
the definition receiving means receives a plurality of 

definitions for a plurality of event monitors for a 
respective plurality of programs, each of said defi- 
nitions specifying that the respective program is 
interested in receiving notification of said event 25 
type. 

13. A computer as set forth in claim 12 wherein: 
the stored event signal transferring means transfers 

the stored event to all of said event monitors; and 
each event monitor includes means for transferring 
the event signal to the respective program during 
normal operation of the program. 

14. A computer as set forth in claim 12 wherein the 
definition receiving means can receive said plurality of 
definitions at substantially different times from the re- 
spective programs during normal operation of the com- 
puter. 

15. A computer as set forth in claim 11 wherein said 
event type is a trace event type; and further comprising 
means for permitting the interested program to process 
the event signal in real time after receipt without inter- 
rupting operation of said computer. 

16. A computer as set forth in claim 12 wherein said 
event type is a trace event type; and further comprising 45 
means for permitting the interested programs to process 
the event signal after receipt in real time independently 
of each other. 

17. A computer as set forth in claim 11 wherein 

the introducing means can receive from a plurality of 50 
programs during normal operation of the computer 
identifications of different, unlisted event types and 
can store the indications of the different event 
types; and 
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the storing means can store signals of the different 
event types in association with the respective 
stored event type indications in absence of one or 
more event monitors which are currently inter- 
ested in receiving notification of the event types. 

18. A computer as set forth in claim 17 wherein: 
the introducing means subsequently receives a plural- 
ity of definitions for a plurality of event monitors 
for the respective plurality of programs, each of 
said definitions specifying that the respective pro- 
gram is interested in receiving notification of the 
respective event type; and 

the stored event signal transferring means transfers 
the stored event signals to the respective event 
monitors. 

19. A computer for managing events, comprising; 
means for dynamically introducing to the computer 

by a program during normal operation of the com- 
puter an unlisted event type and storing an indica- 
tion of the event type; 

means, responsive to a signal of the event and the 
absence of a program which is interested in receiv- 
ing notification of said event type, for storing the 
event signal in association with the stored event 
type indication; 

means for dynamically receiving from a program 
during normal operation of the computer after 
storage of the event signal a definition of an event 
monitor for said event type; 

means for transferring the stored event signal to said 
event monitor, 

means for transferring the event signal from the event 
monitor to the program during normal operation of 
the program; and wherein 

the definition receiving means receives a plurality of 
definitions for a plurality of event monitors for a 
respective plurality of programs, each of said defi- 
nitions specifying that the respective program is 
interested in receiving notification of said event 
type; and further comprising 

means, responsive to a request from one of the pro- 
grams, for dynamically deleting one of the previ- 
ously establised event monitors, and the stored 
event signal transferring means responds to the 
deleting means by not transferring any subsequent 
event signals to said deleted event monitor but 
continuing to transfer subsequent event signals to 
the other event monitors. 

20. A computer as set forth in claim 11 wherein the 
stored event signal transferring means, responds to a 
request from a program not to transfer the stored event 
signal, by not transferring the stored event signal to the 
event monitor. 
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